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