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