1# Visual Customization
2
3Various aspects of Zed's visual layout can be configured via either the settings window or the `settings.json` file, which you can access via {#action zed::OpenSettings} ({#kb zed::OpenSettings}) and {#action zed::OpenSettingsFile} ({#kb zed::OpenSettingsFile}) respectively.
4
5See [Configuring Zed](./configuring-zed.md) for additional information and other non-visual settings.
6
7## Themes
8
9You can install many [themes](./themes.md) and [icon themes](./icon-themes.md) in form of extensions by running {#action zed::Extensions} from the command palette.
10
11You can preview/choose amongst your installed themes and icon themes with {#action theme_selector::Toggle} ({#kb theme_selector::Toggle}) and {#action icon_theme_selector::Toggle} which will modify the following settings:
12
13```json [settings]
14{
15 "theme": "One Dark",
16 "icon_theme": "Zed (Default)"
17}
18```
19
20If you would like to use distinct themes for light mode/dark mode that can be set with:
21
22```json [settings]
23{
24 "theme": {
25 "dark": "One Dark",
26 "light": "One Light",
27 // Mode to use (dark, light) or "system" to follow the OS's light/dark mode (default)
28 "mode": "system"
29 },
30 "icon_theme": {
31 "dark": "Zed (Default)",
32 "light": "Zed (Default)",
33 // Mode to use (dark, light) or "system" to follow the OS's light/dark mode (default)
34 "mode": "system"
35 }
36}
37```
38
39## Fonts
40
41```json [settings]
42 // UI Font. Use ".SystemUIFont" to use the default system font (SF Pro on macOS),
43 // or ".ZedSans" for the bundled default (currently IBM Plex)
44 "ui_font_family": ".SystemUIFont",
45 "ui_font_weight": 400, // Font weight in standard CSS units from 100 to 900.
46 "ui_font_size": 16,
47
48 // Buffer Font - Used by editor buffers
49 // use ".ZedMono" for the bundled default monospace (currently Lilex)
50 "buffer_font_family": "Berkeley Mono", // Font name for editor buffers
51 "buffer_font_size": 15, // Font size for editor buffers
52 "buffer_font_weight": 400, // Font weight in CSS units [100-900]
53 // Line height "comfortable" (1.618), "standard" (1.3) or custom: `{ "custom": 2 }`
54 "buffer_line_height": "comfortable",
55
56 // Terminal Font Settings
57 "terminal": {
58 "font_family": "",
59 "font_size": 15,
60 // Terminal line height: comfortable (1.618), standard(1.3) or `{ "custom": 2 }`
61 "line_height": "standard",
62 },
63
64 // Controls the font size for agent responses in the agent panel.
65 // If not specified, it falls back to the UI font size.
66 "agent_ui_font_size": 15,
67 // Controls the font size for the agent panel's message editor, user message,
68 // and any other snippet of code.
69 "agent_buffer_font_size": 12
70```
71
72### Font ligatures
73
74By default Zed enable font ligatures which will visually combines certain adjacent characters.
75
76For example `=>` will be displayed as `→` and `!=` will be `≠`.
77This is purely cosmetic and the individual characters remain unchanged.
78
79To disable this behavior use:
80
81```json [settings]
82{
83 "buffer_font_features": {
84 "calt": false // Disable ligatures
85 }
86}
87```
88
89### Status Bar
90
91```json [settings]
92{
93 // Whether to show full labels in line indicator or short ones
94 // - `short`: "2 s, 15 l, 32 c"
95 // - `long`: "2 selections, 15 lines, 32 characters"
96 "line_indicator_format": "long"
97
98 // Individual status bar icons can be hidden:
99 // "project_panel": {"button": false },
100 // "outline_panel": {"button": false },
101 // "collaboration_panel": {"button": false },
102 // "git_panel": {"button": false },
103 // "notification_panel": {"button": false },
104 // "agent": {"button": false },
105 // "debugger": {"button": false },
106 // "diagnostics": {"button": false },
107 // "search": {"button": false },
108}
109```
110
111### Titlebar
112
113```json [settings]
114 // Control which items are shown/hidden in the title bar
115 "title_bar": {
116 "show_branch_icon": false, // Show/hide branch icon beside branch switcher
117 "show_branch_name": true, // Show/hide branch name
118 "show_project_items": true, // Show/hide project host and name
119 "show_onboarding_banner": true, // Show/hide onboarding banners
120 "show_user_picture": true, // Show/hide user avatar
121 "show_user_menu": true, // Show/hide app user button
122 "show_sign_in": true, // Show/hide sign-in button
123 "show_menus": false // Show/hide menus
124 },
125```
126
127## Workspace
128
129```json [settings]
130{
131 // Force usage of Zed build in path prompts (file and directory pickers)
132 // instead of OS native pickers (false).
133 "use_system_path_prompts": true,
134 // Force usage of Zed built in confirmation prompts ("Do you want to save?")
135 // instead of OS native prompts (false). On linux this is ignored (always false).
136 "use_system_prompts": true,
137
138 // Active pane styling settings.
139 "active_pane_modifiers": {
140 // Inset border size of the active pane, in pixels.
141 "border_size": 0.0,
142 // Opacity of the inactive panes. 0 means transparent, 1 means opaque.
143 "inactive_opacity": 1.0
144 },
145
146 // Layout mode of the bottom dock: contained, full, left_aligned, right_aligned
147 "bottom_dock_layout": "contained",
148
149 // Whether to resize all the panels in a dock when resizing the dock.
150 // Can be a combination of "left", "right" and "bottom".
151 "resize_all_panels_in_dock": ["left"]
152}
153```
154
155<!--
156TBD: Centered layout related settings
157```json [settings]
158 "centered_layout": {
159 // The relative width of the left padding of the central pane from the
160 // workspace when the centered layout is used.
161 "left_padding": 0.2,
162 // The relative width of the right padding of the central pane from the
163 // workspace when the centered layout is used.
164 "right_padding": 0.2
165 },
166```
167-->
168
169## Editor
170
171```json [settings]
172 // Whether the cursor blinks in the editor.
173 "cursor_blink": true,
174
175 // Cursor shape for the default editor: bar, block, underline, hollow
176 "cursor_shape": null,
177
178 // Highlight the current line in the editor: none, gutter, line, all
179 "current_line_highlight": "all",
180
181 // When does the mouse cursor hide: never, on_typing, on_typing_and_movement
182 "hide_mouse": "on_typing_and_movement",
183
184 // Whether to highlight all occurrences of the selected text in an editor.
185 "selection_highlight": true,
186
187 // Visually show tabs and spaces (none, all, selection, boundary, trailing)
188 "show_whitespaces": "selection",
189 "whitespace_map": { // Which characters to show when `show_whitespaces` enabled
190 "space": "•",
191 "tab": "⟶" // use "→", for a shorter arrow
192 },
193
194 "unnecessary_code_fade": 0.3, // How much to fade out unused code.
195
196 // Hide the values of in variables from visual display in private files
197 "redact_private_values": false,
198
199 // Soft-wrap and rulers
200 "soft_wrap": "none", // none, editor_width, preferred_line_length, bounded
201 "preferred_line_length": 80, // Column to soft-wrap
202 "show_wrap_guides": true, // Show/hide wrap guides (vertical rulers)
203 "wrap_guides": [], // Where to position wrap_guides (character counts)
204
205 // Gutter Settings
206 "gutter": {
207 "line_numbers": true, // Show/hide line numbers in the gutter.
208 "runnables": true, // Show/hide runnables buttons in the gutter.
209 "breakpoints": true, // Show/hide show breakpoints in the gutter.
210 "folds": true, // Show/hide show fold buttons in the gutter.
211 "min_line_number_digits": 4 // Reserve space for N digit line numbers
212 },
213 "relative_line_numbers": "enabled", // Show relative line numbers in gutter
214
215 // Indent guides
216 "indent_guides": {
217 "enabled": true,
218 "line_width": 1, // Width of guides in pixels [1-10]
219 "active_line_width": 1, // Width of active guide in pixels [1-10]
220 "coloring": "fixed", // disabled, fixed, indent_aware
221 "background_coloring": "disabled" // disabled, indent_aware
222 },
223
224 "sticky_scroll": {
225 "enabled": false // Whether to stick scopes to the top of the editor. Disabled by default.
226 }
227```
228
229### Git Blame {#editor-blame}
230
231```json [settings]
232 "git": {
233 "inline_blame": {
234 "enabled": true, // Show/hide inline blame
235 "delay_ms": 0, // Show after delay (ms)
236 "min_column": 0, // Minimum column to inline display blame
237 "padding": 7, // Padding between code and inline blame (em)
238 "show_commit_summary": false // Show/hide commit summary
239 },
240 "hunk_style": "staged_hollow" // staged_hollow, unstaged_hollow
241 }
242```
243
244### Editor Toolbar
245
246```json [settings]
247 // Editor toolbar related settings
248 "toolbar": {
249 "breadcrumbs": true, // Whether to show breadcrumbs.
250 "quick_actions": true, // Whether to show quick action buttons.
251 "selections_menu": true, // Whether to show the Selections menu
252 "agent_review": true, // Whether to show agent review buttons
253 "code_actions": false // Whether to show code action buttons
254 }
255```
256
257### Editor Scrollbar and Minimap {#editor-scrollbar}
258
259```json [settings]
260 // Scrollbar related settings
261 "scrollbar": {
262 // When to show the scrollbar in the editor (auto, system, always, never)
263 "show": "auto",
264 "cursors": true, // Show cursor positions in the scrollbar.
265 "git_diff": true, // Show git diff indicators in the scrollbar.
266 "search_results": true, // Show buffer search results in the scrollbar.
267 "selected_text": true, // Show selected text occurrences in the scrollbar.
268 "selected_symbol": true, // Show selected symbol occurrences in the scrollbar.
269 "diagnostics": "all", // Show diagnostics (none, error, warning, information, all)
270 "axes": {
271 "horizontal": true, // Show/hide the horizontal scrollbar
272 "vertical": true // Show/hide the vertical scrollbar
273 }
274 },
275
276 // Minimap related settings
277 "minimap": {
278 "show": "never", // When to show (auto, always, never)
279 "display_in": "active_editor", // Where to show (active_editor, all_editor)
280 "thumb": "always", // When to show thumb (always, hover)
281 "thumb_border": "left_open", // Thumb border (left_open, right_open, full, none)
282 "max_width_columns": 80, // Maximum width of minimap
283 "current_line_highlight": null // Highlight current line (null, line, gutter)
284 },
285
286 // Control Editor scroll beyond the last line: off, one_page, vertical_scroll_margin
287 "scroll_beyond_last_line": "one_page",
288 // Lines to keep above/below the cursor when scrolling with the keyboard
289 "vertical_scroll_margin": 3,
290 // The number of characters to keep on either side when scrolling with the mouse
291 "horizontal_scroll_margin": 5,
292 // Scroll sensitivity multiplier
293 "scroll_sensitivity": 1.0,
294 // Scroll sensitivity multiplier for fast scrolling (hold alt while scrolling)
295 "fast_scroll_sensitivity": 4.0,
296```
297
298### Editor Tabs
299
300```json [settings]
301 // Maximum number of tabs per pane. Unset for unlimited.
302 "max_tabs": null,
303
304 // Customize the tab bar appearance
305 "tab_bar": {
306 "show": true, // Show/hide the tab bar
307 "show_nav_history_buttons": true, // Show/hide history buttons on tab bar
308 "show_tab_bar_buttons": true // Show hide buttons (new, split, zoom)
309 },
310 "tabs": {
311 "git_status": false, // Color to show git status
312 "close_position": "right", // Close button position (left, right, hidden)
313 "show_close_button": "hover", // Close button shown (hover, always, hidden)
314 "file_icons": false, // Icon showing file type
315 // Show diagnostics in file icon (off, errors, all). Requires file_icons=true
316 "show_diagnostics": "off"
317 }
318```
319
320### Status Bar
321
322```json [settings]
323 "status_bar": {
324 // Show/hide a button that displays the active buffer's language.
325 // Clicking the button brings up the language selector.
326 // Defaults to true.
327 "active_language_button": true,
328 // Show/hide a button that displays the cursor's position.
329 // Clicking the button brings up an input for jumping to a line and column.
330 // Defaults to true.
331 "cursor_position_button": true,
332 // Show/hide a button that displays the buffer's line-ending mode.
333 // Clicking the button brings up the line-ending selector.
334 // Defaults to false.
335 "line_endings_button": false
336 },
337 "global_lsp_settings": {
338 // Show/hide the LSP button in the status bar.
339 // Activity from the LSP is still shown.
340 // Button is not shown if "enable_language_server" if false.
341 "button": true
342 },
343```
344
345### Multibuffer
346
347```json [settings]
348{
349 // The default number of lines to expand excerpts in the multibuffer by.
350 "expand_excerpt_lines": 5,
351 // The default number of lines of context provided for excerpts in the multibuffer by.
352 "excerpt_context_lines": 2
353}
354```
355
356### Editor Completions, Snippets, Actions, Diagnostics {#editor-lsp}
357
358```json [settings]
359 "snippet_sort_order": "inline", // Snippets completions: top, inline, bottom, none
360 "show_completions_on_input": true, // Show completions while typing
361 "show_completion_documentation": true, // Show documentation in completions
362 "auto_signature_help": false, // Show method signatures inside parentheses
363
364 // Whether to show the signature help after completion or a bracket pair inserted.
365 // If `auto_signature_help` is enabled, this setting will be treated as enabled also.
366 "show_signature_help_after_edits": false,
367
368 // Whether to show code action button at start of buffer line.
369 "inline_code_actions": true,
370
371 // Which level to use to filter out diagnostics displayed in the editor:
372 "diagnostics_max_severity": null, // off, error, warning, info, hint, null (all)
373
374 // How to render LSP `textDocument/documentColor` colors in the editor.
375 "lsp_document_colors": "inlay", // none, inlay, border, background
376 // When to show the scrollbar in the completion menu.
377 "completion_menu_scrollbar": "never", // auto, system, always, never
378 // Turn on colorization of brackets in editors (configurable per language)
379 "colorize_brackets": true,
380```
381
382### Edit Predictions {#editor-ai}
383
384```json [settings]
385 "edit_predictions": {
386 "mode": "eager", // Automatically show (eager) or hold-alt (subtle)
387 "enabled_in_text_threads": true // Show/hide predictions in agent text threads
388 },
389 "show_edit_predictions": true // Show/hide predictions in editor
390```
391
392### Editor Inlay Hints
393
394```json [settings]
395{
396 "inlay_hints": {
397 "enabled": false,
398 // Toggle certain types of hints on and off, all switched on by default.
399 "show_type_hints": true,
400 "show_parameter_hints": true,
401 "show_other_hints": true,
402
403 // Whether to show a background for inlay hints (theme `hint.background`)
404 "show_background": false, //
405
406 // Time to wait after editing before requesting hints (0 to disable debounce)
407 "edit_debounce_ms": 700,
408 // Time to wait after scrolling before requesting hints (0 to disable debounce)
409 "scroll_debounce_ms": 50,
410
411 // A set of modifiers which, when pressed, will toggle the visibility of inlay hints.
412 "toggle_on_modifiers_press": {
413 "control": false,
414 "shift": false,
415 "alt": false,
416 "platform": false,
417 "function": false
418 }
419 }
420}
421```
422
423## File Finder
424
425```json [settings]
426 // File Finder Settings
427 "file_finder": {
428 "file_icons": true, // Show/hide file icons
429 "modal_max_width": "small", // Horizontal size: small, medium, large, xlarge, full
430 "git_status": true, // Show the git status for each entry
431 "include_ignored": null // gitignored files in results: true, false, null
432 },
433```
434
435## Project Panel
436
437Project panel can be shown/hidden with {#action project_panel::ToggleFocus} ({#kb project_panel::ToggleFocus}) or with {#action pane::RevealInProjectPanel} ({#kb pane::RevealInProjectPanel}).
438
439```json [settings]
440 // Project Panel Settings
441 "project_panel": {
442 "button": true, // Show/hide button in the status bar
443 "default_width": 240, // Default panel width
444 "dock": "left", // Position of the dock (left, right)
445 "entry_spacing": "comfortable", // Vertical spacing (comfortable, standard)
446 "file_icons": true, // Show/hide file icons
447 "folder_icons": true, // Show/hide folder icons
448 "git_status": true, // Indicate new/updated files
449 "indent_size": 20, // Pixels for each successive indent
450 "auto_reveal_entries": true, // Show file in panel when activating its buffer
451 "auto_fold_dirs": true, // Fold dirs with single subdir
452 "sticky_scroll": true, // Stick parent directories at top of the project panel.
453 "drag_and_drop": true, // Whether drag and drop is enabled
454 "scrollbar": { // Project panel scrollbar settings
455 "show": null // Show/hide: (auto, system, always, never)
456 },
457 "show_diagnostics": "all", //
458 // Settings related to indent guides in the project panel.
459 "indent_guides": {
460 // When to show indent guides in the project panel. (always, never)
461 "show": "always"
462 },
463 // Sort order for entries (directories_first, mixed, files_first)
464 "sort_mode": "directories_first",
465 // Whether to hide the root entry when only one folder is open in the window.
466 "hide_root": false,
467 // Whether to hide the hidden entries in the project panel.
468 "hide_hidden": false
469 }
470```
471
472## Agent Panel
473
474```json [settings]
475 "agent": {
476 "version": "2",
477 "enabled": true, // Enable/disable the agent
478 "button": true, // Show/hide the icon in the status bar
479 "dock": "right", // Where to dock: left, right, bottom
480 "default_width": 640, // Default width (left/right docked)
481 "default_height": 320, // Default height (bottom docked)
482 },
483 // Controls the font size for agent responses in the agent panel.
484 // If not specified, it falls back to the UI font size.
485 "agent_ui_font_size": 15,
486 // Controls the font size for the agent panel's message editor, user message,
487 // and any other snippet of code.
488 "agent_buffer_font_size": 12
489```
490
491See [Zed AI Documentation](./ai/overview.md) for additional non-visual AI settings.
492
493## Terminal Panel
494
495```json [settings]
496 // Terminal Panel Settings
497 "terminal": {
498 "dock": "bottom", // Where to dock: left, right, bottom
499 "button": true, // Show/hide status bar icon
500 "default_width": 640, // Default width (left/right docked)
501 "default_height": 320, // Default height (bottom docked)
502
503 // Set the cursor blinking behavior in the terminal (on, off, terminal_controlled)
504 "blinking": "terminal_controlled",
505 // Default cursor shape for the terminal cursor (block, bar, underline, hollow)
506 "cursor_shape": "block",
507
508 // Environment variables to add to terminal's process environment
509 "env": {
510 // "KEY": "value"
511 },
512
513 // Terminal scrollbar
514 "scrollbar": {
515 "show": null // Show/hide: (auto, system, always, never)
516 },
517 // Terminal Font Settings
518 "font_family": "Fira Code",
519 "font_size": 15,
520 "font_weight": 400,
521 // Terminal line height: comfortable (1.618), standard(1.3) or `{ "custom": 2 }`
522 "line_height": "comfortable",
523
524 "max_scroll_history_lines": 10000, // Scrollback history (0=disable, max=100000)
525 }
526```
527
528See [Terminal settings](./configuring-zed.md#terminal) for additional non-visual customization options.
529
530### Other Panels
531
532```json [settings]
533 // Git Panel
534 "git_panel": {
535 "button": true, // Show/hide status bar icon
536 "dock": "left", // Where to dock: left, right
537 "default_width": 360, // Default width of the git panel.
538 "status_style": "icon", // label_color, icon
539 "sort_by_path": false, // Sort by path (false) or status (true)
540 "scrollbar": {
541 "show": null // Show/hide: (auto, system, always, never)
542 }
543 },
544
545 // Debugger Panel
546 "debugger": {
547 "dock": "bottom", // Where to dock: left, right, bottom
548 "button": true // Show/hide status bar icon
549 },
550
551 // Outline Panel
552 "outline_panel": {
553 "button": true, // Show/hide status bar icon
554 "default_width": 300, // Default width of the git panel
555 "dock": "left", // Where to dock: left, right
556 "file_icons": true, // Show/hide file_icons
557 "folder_icons": true, // Show file_icons (true), chevrons (false) for dirs
558 "git_status": true, // Show git status
559 "indent_size": 20, // Indentation for nested items (pixels)
560 "indent_guides": {
561 "show": "always" // Show indent guides (always, never)
562 },
563 "auto_reveal_entries": true, // Show file in panel when activating its buffer
564 "auto_fold_dirs": true, // Fold dirs with single subdir
565 "scrollbar": { // Project panel scrollbar settings
566 "show": null // Show/hide: (auto, system, always, never)
567 }
568 }
569```
570
571## Collaboration Panels
572
573```json [settings]
574{
575 // Collaboration Panel
576 "collaboration_panel": {
577 "button": true, // Show/hide status bar icon
578 "dock": "left", // Where to dock: left, right
579 "default_width": 240 // Default width of the collaboration panel.
580 },
581 "show_call_status_icon": true, // Shown call status in the OS status bar.
582
583 // Notification Panel
584 "notification_panel": {
585 // Whether to show the notification panel button in the status bar.
586 "button": true,
587 // Where to dock the notification panel. Can be 'left' or 'right'.
588 "dock": "right",
589 // Default width of the notification panel.
590 "default_width": 380
591 }
592}
593```