|
| 1 | +--- |
| 2 | +title: Recommended Zed `keymap.json` Settings |
| 3 | +date: 2025-12-26 |
| 4 | +category: IDE |
| 5 | +description: I share my minimal recommended `keymap.json` settings for Zed. |
| 6 | +tags: [zed, ai] |
| 7 | +recommended: true |
| 8 | +thumbnail: assets/img/zed_icon.png |
| 9 | +--- |
| 10 | + |
| 11 | +Hello! Pan here. |
| 12 | + |
| 13 | +In this post I describe my recommended `keymap.json` settings for the Zed editor — the key mappings I find convenient to set up. |
| 14 | +I also previously wrote about recommended IDE settings in `settings.json`, so you might want to read that as well: |
| 15 | +[!CARD](https://breadmotion.github.io/WebSite/blog/en/blog_00023.html) |
| 16 | + |
| 17 | +## Introduction |
| 18 | + |
| 19 | +Zed provides a customizable keybinding system that is easy to configure. While some IDEs let you change bindings via `settings.json`, Zed primarily uses `keymap.json` for most custom key mappings (writing them in `settings.json` may also work in some cases). |
| 20 | + |
| 21 | +Examples of other editors/IDEs with configurable bindings: |
| 22 | +- VSCode |
| 23 | +- Atom |
| 24 | +- Emacs |
| 25 | +- JetBrains |
| 26 | +- Sublime Text |
| 27 | +- TextMate |
| 28 | +- Cursor |
| 29 | + |
| 30 | +For the official documentation, see the Key Bindings section here: |
| 31 | +[!CARD](https://zed.dev/docs/key-bindings#contexts) |
| 32 | + |
| 33 | +### How to configure |
| 34 | + |
| 35 | +You can edit the keymap either by directly editing `keymap.json` or by opening the keymap editor via the command palette (`Ctrl-Shift-P`) and selecting `zed: open keymap`. |
| 36 | +The GUI-based keymap editor is convenient because it allows configuring bindings without knowing the exact JSON syntax. |
| 37 | + |
| 38 | +| | `keymap.json` | Keymap editor | |
| 39 | +| :--- | :--- | :--- | |
| 40 | +| Characteristics | Allows fine-grained control | Configure without knowing the syntax | |
| 41 | +| Recommended for | People who prefer editing from the keyboard or want custom/advanced behaviors | People who want an easy, guided UI | |
| 42 | + |
| 43 | + |
| 44 | + |
| 45 | +### Basic syntax |
| 46 | + |
| 47 | +Keymap entries generally follow this structure. Zed supports sequences of multiple keys (entered in order), so within the `"bindings"` map you can represent multiple-key sequences by writing them with spaces (in the JSON representation you'll use `-` as part of the key token where required). |
| 48 | + |
| 49 | +Example: |
| 50 | + |
| 51 | +```json |
| 52 | +[ |
| 53 | + { |
| 54 | + "bindings": { |
| 55 | + "ctrl-'": "command", |
| 56 | + "shift-ctrl-'": "command" |
| 57 | + } |
| 58 | + }, |
| 59 | + { |
| 60 | + "context": "context", |
| 61 | + "bindings": { |
| 62 | + "fn-n": "command" |
| 63 | + } |
| 64 | + } |
| 65 | +] |
| 66 | +``` |
| 67 | + |
| 68 | +For more details on the syntax, refer to the `Keybinding Syntax` section in the official docs: |
| 69 | +https://zed.dev/docs/key-bindings#contexts |
| 70 | + |
| 71 | +## My recommended settings |
| 72 | + |
| 73 | +There are many details such as contexts, precedence, and remapping rules, but since this article focuses on practical recommendations, I'll list the minimal changes I suggest adding to your `keymap.json`. |
| 74 | +Note: I use an English-layout keyboard without a numeric keypad. |
| 75 | + |
| 76 | +... |
| 77 | + |
| 78 | +That said, my conclusion is that you should generally keep most bindings at their defaults. For the reasons explained later, you only need to add the following minimal entries to `keymap.json` — you generally don't need to touch the rest: |
| 79 | + |
| 80 | +```json |
| 81 | +[ |
| 82 | + { |
| 83 | + "context": "Editor", |
| 84 | + "bindings": { |
| 85 | + "ctrl-shift-'": "terminal_panel::Toggle" // default is "ctrl-`" |
| 86 | + } |
| 87 | + }, |
| 88 | + { |
| 89 | + "context": "Panel", |
| 90 | + "bindings": { |
| 91 | + "ctrl-shift-]": "editor::ToggleFocus" |
| 92 | + } |
| 93 | + } |
| 94 | +] |
| 95 | +``` |
| 96 | + |
| 97 | +There are two reasons for this choice. |
| 98 | + |
| 99 | +The above mappings addressed the most-needed operations for me that weren't available in the default keybindings. Adding these allows the following operations using only keyboard shortcuts: |
| 100 | + - Focus the agent panel at any time, so you can send prompts and interact with the AI chat without interrupting your workflow. |
| 101 | + - Focus the terminal panel at any time. |
| 102 | + - The default binding (`ctrl-b`) toggles the left sidebar. If you use the default right-docked layout for the agent and terminal panels, toggling the left sidebar twice while those panels are focused will return focus to the file editor — so you can always get back to editing quickly. |
| 103 | + |
| 104 | +Most of the actions you need can be found and set via the command palette (`Ctrl-Shift-P`), and many users are already familiar with standard IDE/global keybindings. Zed also offers presets to make keybindings feel like other editors (e.g., VSCode-like), so making large, arbitrary changes is often unnecessary and may be counterproductive. Instead, follow this small process when you want a change: |
| 105 | + |
| 106 | +1. Notice a single operation you want to simplify to a single keybinding. |
| 107 | +2. Search the command in the command palette or check the official documentation to see if the command exists. |
| 108 | +3. Assign the desired keybinding to that command. |
| 109 | + |
| 110 | +You can use either the direct `keymap.json` edit or the keymap editor GUI for step 3. |
| 111 | + |
| 112 | +## Conclusion |
| 113 | + |
| 114 | +If you make sure navigation between panels is well-covered by your keymap, you can leave most shortcuts at their defaults and only remap the few keys that improve your workflow. Once you map the critical panel-navigation shortcuts, you should be able to work smoothly. |
| 115 | + |
| 116 | +Enjoy a comfortable Zed experience! |
0 commit comments