1# Key bindings
  2
  3Zed has a very customizable key binding system — you can tweak everything to work exactly how your fingers expect!
  4
  5## Predefined keymaps
  6
  7If you're used to a specific editor's defaults you can set a `base_keymap` in your [settings file](./configuring-zed.md). We currently have:
  8
  9- VSCode (default)
 10- Atom
 11- Emacs (Beta)
 12- JetBrains
 13- SublimeText
 14- TextMate
 15- None (disables _all_ key bindings)
 16
 17You can also enable `vim_mode`, which adds vim bindings too.
 18
 19## User keymaps
 20
 21Zed reads your keymap from `~/.config/zed/keymap.json`. You can open the file within Zed with {#kb zed::OpenKeymap}, or via `zed: Open Keymap` in the command palette.
 22
 23The file contains a JSON array of objects with `"bindings"`. If no `"context"` is set the bindings are always active. If it is set the binding is only active when the [context matches](#contexts).
 24
 25Within each binding section a [key sequence](#keybinding-syntax) is mapped to an [action](#actions). If conflicts are detected they are resolved as [described below](#precedence).
 26
 27If you are using a non-QWERTY, Latin-character keyboard, you may want to set `use_layout_keys` to `true`. See [Non-QWERTY keyboards](#non-qwerty-keyboards) for more information.
 28
 29For example:
 30
 31```json
 32[
 33  {
 34    "bindings": {
 35      "ctrl-right": "editor::SelectLargerSyntaxNode",
 36      "ctrl-left": "editor::SelectSmallerSyntaxNode"
 37    }
 38  },
 39  {
 40    "context": "ProjectPanel && not_editing",
 41    "bindings": {
 42      "o": "project_panel::Open"
 43    }
 44  }
 45]
 46```
 47
 48You can see all of Zed's default bindings in the default keymaps for [MacOS](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-macos.json) or [Linux](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json).
 49
 50If you want to debug problems with custom keymaps you can use `dev: Open Key Context View` from the command palette. Please file [an issue](https://github.com/zed-industries/zed) if you run into something you think should work but isn't.
 51
 52### Keybinding syntax
 53
 54Zed has the ability to match against not just a single keypress, but a sequence of keys typed in order. Each key in the `"bindings"` map is a sequence of keypresses separated with a space.
 55
 56Each keypress is a sequence of modifiers followed by a key. The modifiers are:
 57
 58- `ctrl-` The control key
 59- `cmd-`, `win-` or `super-` for the platform modifier (Command on macOS, Windows key on Windows, and the Super key on Linux).
 60- `alt-` for alt (option on macOS)
 61- `shift-` The shift key
 62- `fn-` The function key
 63- `secondary-` Equivalent to `cmd` when Zed is running on macOS and `ctrl` when on Windows and Linux
 64
 65The keys can be any single unicode codepoint that your keyboard generates (for example `a`, `0`, `£` or `ç`), or any named key (`tab`, `f1`, `shift`, or `cmd`). If you are using a non-Latin layout (e.g. Cyrillic), you can bind either to the cyrillic character, or the latin character that key generates with `cmd` pressed.
 66
 67A few examples:
 68
 69```json
 70 "bindings": {
 71   "cmd-k cmd-s": "zed::OpenKeymap", // matches ⌘-k then ⌘-s
 72   "space e": "editor::Complete", // type space then e
 73   "ç": "editor::Complete", // matches ⌥-c
 74   "shift shift": "file_finder::Toggle", // matches pressing and releasing shift twice
 75 }
 76```
 77
 78The `shift-` modifier can only be used in combination with a letter to indicate the uppercase version. For example `shift-g` matches typing `G`. Although on many keyboards shift is used to type punctuation characters like `(`, the keypress is not considered to be modified and so `shift-(` does not match.
 79
 80The `alt-` modifier can be used on many layouts to generate a different key. For example on macOS US keyboard the combination `alt-c` types `ç`. You can match against either in your keymap file, though by convention Zed spells this combination as `alt-c`.
 81
 82It is possible to match against typing a modifier key on its own. For example `shift shift` can be used to implement JetBrains search everywhere shortcut. In this case the binding happens on key release instead of keypress.
 83
 84### Contexts
 85
 86If a binding group has a `"context"` key it will be matched against the currently active contexts in Zed.
 87
 88Zed's contexts make up a tree, with the root being `Workspace`. Workspaces contain Panes and Panels, and Panes contain Editors, etc. The easiest way to see what contexts are active at a given moment is the key context view, which you can get to with `dev: Open Key Context View` in the command palette.
 89
 90Contexts can contain extra attributes in addition to the name, so that you can (for example) match only in markdown files with `"context": "Editor && extension==md"`. It's worth noting that you can only use attributes at the level they are defined.
 91
 92For example:
 93
 94```
 95# in an editor, it might look like this:
 96Workspace os=macos keyboard_layout=com.apple.keylayout.QWERTY
 97  Pane
 98    Editor mode=full extension=md inline_completion vim_mode=insert
 99
100# in the project panel
101Workspace os=macos
102  Dock
103    ProjectPanel not_editing
104```
105
106Context expressions can contain the following syntax:
107
108- `X && Y`, `X || Y` to and/or two conditions
109- `!X` to negate a condition
110- `(X)` for grouping
111- `X > Y` to match if a parent in the tree matches X and this layer matches Y.
112
113If you're using Vim mode, we have information on how [vim modes influence the context](./vim.md#contexts)
114
115### Actions
116
117Pretty much all of Zed's functionality is exposed as actions. Although there is
118no explicitly documented list, you can find most of them by searching in the
119command palette, by looking in the default keymaps for
120[MacOS](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-macos.json)
121or
122[Linux](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json), or by using Zed's autocomplete in your keymap file.
123
124Most actions do not require any arguments, and so you can bind them as strings: `"ctrl-a": "language_selector::Toggle"`. Some require a single argument, and must be bound as an array: `"cmd-1": ["workspace::ActivatePane", 0]`. Some actions require multiple arguments, and are bound as an array of a string and an object: `"ctrl-a": ["pane::DeploySearch", { "replace_enabled": true }]`.
125
126### Precedence
127
128When multiple keybindings have the same keystroke and are active at the same time, precedence is resolved in two ways:
129
130- Bindings that match on lower nodes in the context tree win. This means that if you have a binding with a context of `Editor` it will take precedence over a binding with a context of `Workspace`. Bindings with no context match at the lowest level in the tree.
131- If there are multiple bindings that match at the same level in the tree, then the binding defined later takes precedence. As user keybindings are loaded after system keybindings, this allows user bindings to take precedence over builtin keybindings.
132
133The other kind of conflict that arises is when you have two bindings, one of which is a prefix of the other. For example if you have `"ctrl-w":"editor::DeleteToNextWordEnd"` and `"ctrl-w left":"editor::DeleteToEndOfLine"`.
134
135When this happens, and both bindings are active in the current context, Zed will wait for 1 second after you type `ctrl-w` to see if you're about to type `left`. If you don't type anything, or if you type a different key, then `DeleteToNextWordEnd` will be triggered. If you do, then `DeleteToEndOfLine` will be triggered.
136
137### Non-QWERTY keyboards
138
139Zed's support for non-QWERTY keyboards is still a work in progress.
140
141If your keyboard can type the full ASCII ranges (DVORAK, COLEMAK, etc.) then shortcuts should work as you expect.
142
143Otherwise, read on...
144
145#### macOS
146
147On Cyrillic, Hebrew, Armenian, and other keyboards that are mostly non-ASCII; macOS automatically maps keys to the ASCII range when `cmd` is held. Zed takes this a step further and it can always match key-presses against either the ASCII layout, or the real layout regardless of modifiers, and regardless of the `use_key_equivalents` setting. For example in Thai, pressing `ctrl-ๆ` will match bindings associated with `ctrl-q` or `ctrl-ๆ`
148
149On keyboards that support extended Latin alphabets (French AZERTY, German QWERTZ, etc.) it is often not possible to type the entire ASCII range without `option`. This introduces an ambiguity, `option-2` produces `@`. To ensure that all the builtin keyboard shortcuts can still be typed on these keyboards we move key-bindings around. For example, shortcuts bound to `@` on QWERTY are moved to `"` on a Spanish layout. This mapping is based on the macOS system defaults and can be seen by running `dev: Open Key Context View` from the command palette.
150
151If you are defining shortcuts in your personal keymap, you can opt into the key equivalent mapping by setting `use_key_equivalents` to `true` in your keymap:
152
153```json
154[
155  {
156    "use_key_equivalents": true,
157    "bindings": {
158      "ctrl->": "editor::Indent" // parsed as ctrl-: when a German QWERTZ keyboard is active
159    }
160  }
161]
162```
163
164### Linux
165
166Since v0.196.0 on Linux if the key that you type doesn't produce an ASCII character then we use the QWERTY-layout equivalent key for keyboard shortcuts. This means that many shortcuts can be typed on many layouts.
167
168We do not yet move shortcuts around to ensure that all the builtin shortcuts can be typed on every layout; so if there are some ASCII characters that cannot be typed, and your keyboard layout has different ASCII characters on the same keys as would be needed to type them, you may need to add custom key bindings to make this work. We do intend to fix this at some point, and help is very much wanted!
169
170## Tips and tricks
171
172### Disabling a binding
173
174If you'd like a given binding to do nothing in a given context you can use
175`null` as the action. This is useful if you hit the keybinding by accident and
176want to disable it, or if you want to type the character that would be typed by
177the sequence, or if you want to disable multikey bindings starting with that key.
178
179```json
180[
181  {
182    "context": "Workspace",
183    "bindings": {
184      "cmd-r": null // cmd-r will do nothing when the Workspace context is active
185    }
186  }
187]
188```
189
190A `null` binding follows the same precedence rules as normal actions. So disables all bindings that would match further up in the tree too. If you'd like a binding that matches further up in the tree to take precedence over a lower binding, you need to rebind it to the action you want in the context you want.
191
192This is useful for preventing Zed from falling back to a default keybinding when the action you specified is conditional and propagates. For example, `buffer_search::DeployReplace` only triggers when the search bar is not in view. If the search bar is in view, it would propagate and trigger the default action set for that binding, such as opening the right dock. To prevent this from happening:
193
194```json
195[
196  {
197    "context": "Workspace",
198    "bindings": {
199      "cmd-r": null // cmd-r will do nothing when the search bar is in view
200    }
201  },
202  {
203    "context": "Workspace",
204    "bindings": {
205      "cmd-r": "buffer_search::DeployReplace" // cmd-r will deploy replace when the search bar is not in view
206    }
207  }
208]
209```
210
211### Remapping keys
212
213A common request is to be able to map from a single keystroke to a sequence. You can do this with the `workspace::SendKeystrokes` action.
214
215```json
216[
217  {
218    "bindings": {
219      "alt-down": ["workspace::SendKeystrokes", "down down down down"],
220      "cmd-alt-c": [
221        "workspace::SendKeystrokes",
222        "cmd-shift-p copy relative path enter"
223      ],
224      "cmd-alt-r": ["workspace::SendKeystrokes", "cmd-p README enter"]
225    }
226  },
227  {
228    "context": "Editor && vim_mode == insert",
229    "bindings": {
230      "j k": ["workspace::SendKeystrokes", "escape"]
231    }
232  }
233]
234```
235
236There are some limitations to this, notably:
237
238- Any asynchronous operation will not happen until after all your key bindings have been dispatched. For example this means that while you can use a binding to open a file (as in the `cmd-alt-r` example) you cannot send further keystrokes and hope to have them interpreted by the new view.
239- Other examples of asynchronous things are: opening the command palette, communicating with a language server, changing the language of a buffer, anything that hits the network.
240- There is a limit of 100 simulated keys at a time.
241
242The argument to `SendKeystrokes` is a space-separated list of keystrokes (using the same syntax as above). Due to the way that keystrokes are parsed, any segment that is not recognized as a keypress will be sent verbatim to the currently focused input field.
243
244If the argument to `SendKeystrokes` contains the binding used to trigger it, it will use the next-highest-precedence definition of that binding. This allows you to extend the default behavior of a key binding.
245
246### Forward keys to terminal
247
248If you're on Linux or Windows, you might find yourself wanting to forward key combinations to the built-in terminal instead of them being handled by Zed.
249
250For example, `ctrl-n` creates a new tab in Zed on Linux. If you want to send `ctrl-n` to the built-in terminal when it's focused, add the following to your keymap:
251
252```json
253{
254  "context": "Terminal",
255  "bindings": {
256    "ctrl-n": ["terminal::SendKeystroke", "ctrl-n"]
257  }
258}
259```
260
261### Task Key bindings
262
263You can also bind keys to launch Zed Tasks defined in your tasks.json.
264See the [tasks documentation](tasks.md#custom-keybindings-for-tasks) for more.