@@ -1,14 +1,14 @@
# Appearance
-Zed's visual appearance is highly configurable. You can change themes, fonts, icon styles, and dozens of UI elements to match your preferences.
+Customize Zed's visual appearance to match your preferences. This guide covers themes, fonts, icons, and other visual settings.
-This page covers the essentials to get you started quickly, outlines how settings work, and points you to detailed documentation for specific customizations.
+For information on how the settings system works, see [Configuring Zed](./configuring-zed.md).
## Customize Zed in 5 Minutes
Here's how to make Zed feel like home:
-1. **Pick a theme**: Open the command palette with {#kb theme_selector::Toggle} and type "theme" to open the Theme Selector. Arrow through the list to preview themes in real time, and press Enter to apply.
+1. **Pick a theme**: Press {#kb theme_selector::Toggle} to open the Theme Selector. Arrow through the list to preview themes in real time, and press Enter to apply.
2. **Choose an icon theme**: Run `icon theme selector: toggle` from the command palette to browse icon themes.
@@ -18,85 +18,105 @@ Here's how to make Zed feel like home:
That's it. You now have a personalized Zed setup.
-## How Settings Work
+## Themes
-The **Settings Editor** ({#kb zed::OpenSettings}) is the primary way to configure Zed. It provides a searchable interface where you can browse available settings, see their current values, and make changes. As you type in the search box, matching settings appear with descriptions and controls to modify them.
-
-Changes you make in the Settings Editor are saved automatically to your settings file.
-
-### User Settings vs Project Settings
-
-Zed supports two levels of configuration:
-
-- **User settings** apply globally across all projects. These are your defaults.
-
-- **Project settings** override user settings for a specific project. Create a `.zed/settings.json` file in your project root to customize behavior per-codebase (for example, different tab sizes or formatters for different projects).
-
-### Editing Settings as JSON
+Install themes from the Extensions page ({#action zed::Extensions}), then switch between them with the Theme Selector ({#kb theme_selector::Toggle}).
-If you prefer working with JSON directly, open your settings file with {#kb zed::OpenSettingsFile}. This file is located at:
+Zed supports separate themes for light and dark mode with automatic switching based on your system preference:
-- macOS/Linux: `~/.config/zed/settings.json`
-- Windows: `%APPDATA%\Zed\settings.json`
+```json [settings]
+{
+ "theme": {
+ "mode": "system",
+ "light": "One Light",
+ "dark": "One Dark"
+ }
+}
+```
-The Settings Editor and JSON file represent the same configuration—changes in one are reflected in the other.
+You can also override specific theme attributes for fine-grained control.
-> **Tip:** Some advanced settings aren't yet available in the Settings Editor. For full control, edit the JSON file directly.
+→ [Themes documentation](./themes.md)
-### Example: Changing Your Theme
+## Icon Themes
-Using the Settings Editor:
-1. Press {#kb zed::OpenSettings}
-2. Search for "theme"
-3. Select your preferred theme from the dropdown
+Customize file and folder icons in the Project Panel and tabs. Browse available icon themes with the Icon Theme Selector (`icon theme selector: toggle` in the command palette).
-Or add this to your `settings.json`:
+Like color themes, icon themes support separate light and dark variants:
```json [settings]
{
- "theme": {
+ "icon_theme": {
"mode": "system",
- "light": "One Light",
- "dark": "One Dark"
+ "light": "Zed (Default)",
+ "dark": "Zed (Default)"
}
}
```
-## Using Settings Deep Links
+→ [Icon Themes documentation](./icon-themes.md)
-Zed supports deep links that open specific settings directly. These are useful for:
+## Fonts
-- Sharing configuration tips with teammates
-- Quick access from documentation
-- Automation and scripting
+Zed uses three font settings for different contexts:
-Deep links follow the format `zed://settings/setting_name`. For example, `zed://settings/theme` opens the theme settings.
+| Setting | Used for |
+|---------|----------|
+| `buffer_font_family` | Editor text |
+| `ui_font_family` | Interface elements |
+| `terminal.font_family` | Terminal |
-## Detailed Customization
+Example configuration:
-### Themes
+```json [settings]
+{
+ "buffer_font_family": "JetBrains Mono",
+ "buffer_font_size": 14,
+ "ui_font_family": "Inter",
+ "ui_font_size": 16,
+ "terminal": {
+ "font_family": "JetBrains Mono",
+ "font_size": 14
+ }
+}
+```
-Install themes from the Extensions page ({#action zed::Extensions}), then switch between them with the Theme Selector ({#kb theme_selector::Toggle}).
+### Font Ligatures
-Zed supports separate themes for light and dark mode, automatic switching based on your system preference, and per-theme overrides for fine-grained control.
+To disable font ligatures:
-→ [Themes documentation](./themes.md)
+```json [settings]
+{
+ "buffer_font_features": {
+ "calt": false
+ }
+}
+```
-### Icon Themes
+### Line Height
-Customize file and folder icons in the project panel and tabs. Browse available icon themes with the Icon Theme Selector.
+Adjust line spacing with `buffer_line_height`:
-→ [Icon Themes documentation](./icon-themes.md)
+- `"comfortable"` — 1.618 ratio (default)
+- `"standard"` — 1.3 ratio
+- `{ "custom": 1.5 }` — Custom ratio
+
+## UI Elements
-### Fonts & Visual Tweaks
+Zed provides extensive control over UI elements including:
-Configure fonts for the editor buffer, UI, and terminal independently. Adjust line height, enable or disable ligatures, and tweak dozens of visual elements like the status bar, tab bar, scrollbar, and panels.
+- **Tab bar** — Show/hide, navigation buttons, file icons, git status
+- **Status bar** — Language selector, cursor position, line endings
+- **Scrollbar** — Visibility, git diff indicators, search results
+- **Minimap** — Code overview display
+- **Gutter** — Line numbers, fold indicators, breakpoints
+- **Panels** — Project Panel, Terminal, Agent Panel sizing and docking
-→ [Visual Customization documentation](./visual-customization.md)
+→ [Visual Customization documentation](./visual-customization.md) for all UI element settings
## What's Next
+- [Configuring Zed](./configuring-zed.md) — How the settings system works
- [Key bindings](./key-bindings.md) — Customize keyboard shortcuts
- [Vim Mode](./vim.md) — Enable modal editing
-- [Snippets](./snippets.md) — Create custom code snippets
-- [All Settings](./configuring-zed.md) — Complete settings reference
+- [All Settings](./reference/all-settings.md) — Complete settings reference
@@ -1,72 +1,133 @@
# Configuring Zed
-Zed is designed to be configured: we want to fit your workflow and preferences exactly. We provide default settings that are designed to be a comfortable starting point for as many people as possible, but we hope you will enjoy tweaking it to make it feel incredible.
+This guide explains how Zed's settings system works, including the Settings Editor, JSON configuration files, and project-specific settings.
-In addition to the settings described here, you may also want to change your [theme](./themes.md), configure your [key bindings](./key-bindings.md), set up [tasks](./tasks.md) or install [extensions](https://github.com/zed-industries/extensions).
+For visual customization (themes, fonts, icons), see [Appearance](./appearance.md).
## Settings Editor
-You can browse through many of the supported settings via the Settings Editor, which can be opened with the {#kb zed::OpenSettings} keybinding, or through the `zed: open settings` action in the command palette. Through it, you can customize your local, user settings as well as project settings.
+The **Settings Editor** ({#kb zed::OpenSettings}) is the primary way to configure Zed. It provides a searchable interface where you can browse available settings, see their current values, and make changes.
-> Note that not all settings that Zed supports are available through the Settings Editor yet.
-> Some more intricate ones, such as language formatters, can only be changed through the JSON settings file {#kb zed::OpenSettingsFile}.
+To open it:
+- Press {#kb zed::OpenSettings}
+- Or run `zed: open settings` from the command palette
-## User Settings File
+As you type in the search box, matching settings appear with descriptions and controls to modify them. Changes save automatically to your settings file.
-<!--
-TBD: Settings files. Rewrite with "remote settings" in mind (e.g. `local settings` on the remote host).
-Consider renaming `zed: Open Local Settings` to `zed: Open Project Settings`.
+> **Note:** Not all settings are available in the Settings Editor yet. Some advanced options, like language formatters, require editing the JSON file directly.
-TBD: Add settings documentation about how settings are merged as overlays. E.g. project>local>default. Note how settings that are maps are merged, but settings that are arrays are replaced and must include the defaults.
--->
+## Settings Files
-Your settings JSON file can be opened with {#kb zed::OpenSettingsFile}.
-By default it is located at `~/.config/zed/settings.json`, though if you have `XDG_CONFIG_HOME` in your environment on Linux it will be at `$XDG_CONFIG_HOME/zed/settings.json` instead.
+### User Settings
-Whatever you have added to your user settings file gets merged with any local configuration inside your projects.
+Your user settings apply globally across all projects. Open the file with {#kb zed::OpenSettingsFile} or run `zed: open settings file` from the command palette.
+
+The file is located at:
+- macOS: `~/.config/zed/settings.json`
+- Linux: `~/.config/zed/settings.json` (or `$XDG_CONFIG_HOME/zed/settings.json`)
+- Windows: `%APPDATA%\Zed\settings.json`
+
+The syntax is JSON with support for `//` comments.
### Default Settings
-In the Settings Editor, the values you see set are the default ones.
-You can also verify them in JSON by running {#action zed::OpenDefaultSettings} from the command palette.
+To see all available settings with their default values, run {#action zed::OpenDefaultSettings} from the command palette. This opens a read-only reference you can use when editing your own settings.
+
+### Project Settings
+
+Override user settings for a specific project by creating a `.zed/settings.json` file in your project root. Run {#action zed::OpenProjectSettings} to create this file.
+
+Project settings take precedence over user settings for that project only.
+
+```json [settings]
+// .zed/settings.json
+{
+ "tab_size": 2,
+ "formatter": "prettier",
+ "format_on_save": "on"
+}
+```
+
+You can also add settings files in subdirectories for more granular control.
-Extensions that provide language servers may also provide default settings for those language servers.
+**Limitation:** Not all settings can be set at the project level. Settings that affect the editor globally (like `theme` or `vim_mode`) only work in user settings. Project settings are limited to editor behavior and language tooling options like `tab_size`, `formatter`, and `format_on_save`.
-## Project Settings File
+## How Settings Merge
-Similarly to user files, you can open your project settings file by running {#action zed::OpenProjectSettings} from the command palette.
-This will create a `.zed` directory containing`.zed/settings.json`.
+Settings are applied in layers:
-Although most projects will only need one settings file at the root, you can add more local settings files for subdirectories as needed.
-Not all settings can be set in local files, just those that impact the behavior of the editor and language tooling.
-For example you can set `tab_size`, `formatter` etc. but not `theme`, `vim_mode` and similar.
+1. **Default settings** — Zed's built-in defaults
+2. **User settings** — Your global preferences
+3. **Project settings** — Project-specific overrides
-The syntax for configuration files is a super-set of JSON that allows `//` comments.
+Later layers override earlier ones. For object settings (like `terminal`), properties merge rather than replace entirely.
-## Per-release Channel Overrides
+## Per-Release Channel Overrides
-Zed reads the same `settings.json` across all release channels (Stable, Preview or Nightly).
-However, you can scope overrides to a specific channel by adding top-level `stable`, `preview`, `nightly` or `dev` objects.
-They are merged into the base configuration with settings from these keys taking precedence upon launching the specified build. For example:
+Use different settings for Stable, Preview, or Nightly builds by adding top-level channel keys:
```json [settings]
{
- "theme": "sunset",
+ "theme": "One Dark",
"vim_mode": false,
"nightly": {
- "theme": "cave-light",
+ "theme": "Rosé Pine",
"vim_mode": true
},
"preview": {
- "theme": "zed-dark"
+ "theme": "Catppuccin Mocha"
}
}
```
-With this configuration, Stable keeps all base preferences, Preview switches to `zed-dark`, and Nightly enables Vim mode with a different theme.
+With this configuration:
+- **Stable** uses One Dark with vim mode off
+- **Preview** uses Catppuccin Mocha with vim mode off
+- **Nightly** uses Rosé Pine with vim mode on
+
+Changes made in the Settings Editor apply across all channels.
+
+## Settings Deep Links
+
+Zed supports deep links that open specific settings directly:
-Changing settings in the Settings Editor will always apply the change across all channels.
+```
+zed://settings/theme
+zed://settings/vim_mode
+zed://settings/buffer_font_size
+```
+
+These are useful for sharing configuration tips or linking from documentation.
+
+## Example Configuration
+
+```json [settings]
+{
+ "theme": {
+ "mode": "system",
+ "light": "One Light",
+ "dark": "One Dark"
+ },
+ "buffer_font_family": "JetBrains Mono",
+ "buffer_font_size": 14,
+ "tab_size": 2,
+ "format_on_save": "on",
+ "autosave": "on_focus_change",
+ "vim_mode": false,
+ "terminal": {
+ "font_family": "JetBrains Mono",
+ "font_size": 14
+ },
+ "languages": {
+ "Python": {
+ "tab_size": 4
+ }
+ }
+}
+```
-## All Settings Reference
+## What's Next
-For a complete list of all available settings, see the [All Settings](./reference/all-settings.md) reference.
+- [Appearance](./appearance.md) — Themes, fonts, and visual customization
+- [Key bindings](./key-bindings.md) — Customize keyboard shortcuts
+- [All Settings](./reference/all-settings.md) — Complete settings reference