Keybindings

A keybinding maps a key chord to a command — your own or a built-in. Keybindings are pure JSON: no code, no main, no activation events required. They register from the manifest at install/enable time.

• 1. Declare the binding
• 2. Key syntax
• 3. The when context
• 4. Binding to your own command
• 5. Binding to a built-in command
• Related

1. Declare the binding

"contributes": {
  "keybindings": [
    { "key": "cmd+k cmd+t", "command": "dracula-warm.apply", "when": "editorFocus" }
  ]
}

Field	Required	Constraint
key	yes	Space-separated chords (≥ 1 char). See below.
command	yes	^[A-Za-z0-9_.-]+$. A contributed or built-in command.
when	no	"editorFocus" or "always".

2. Key syntax

• A binding is a space-separated sequence of chords. A single chord is one combo; multiple chords form a multi-step (VS Code-style) sequence.
• Within a chord, join modifiers and the key with +.
• Tokens: cmd ctrl alt shift plus a key.
• cmd is cross-platform: it maps to ⌘ on macOS and Ctrl elsewhere.

Example	Meaning
cmd+k cmd+t	Press Cmd/Ctrl+K, then Cmd/Ctrl+T (a chord).
cmd+k cmd+d	Cmd/Ctrl+K then Cmd/Ctrl+D.
ctrl+shift+l	A single combo with two modifiers.
alt+up	Alt + arrow up.

Avoid collisions

Aero already binds several chords (e.g. Cmd/Ctrl+Shift+E → Explorer, Cmd/Ctrl+Shift+F → Search, Cmd/Ctrl+B → toggle sidebar, Cmd/Ctrl+J → editor, Ctrl+\`` → terminal). Prefer the cmd+k …` two-step namespace for extension bindings to stay clear of built-ins.

3. The when context

when gates the binding to a context. v1 supports a small set:

Value	The binding fires…
editorFocus	only when the editor (Monaco) has focus.
always	regardless of focus.

Omit when to use the host's default. Use editorFocus for bindings that act on the editor (insert text, run a formatter) so they don't fire while you're typing in the terminal or a panel.

4. Binding to your own command

A keybinding usually points at a command you also contribute:

{
  "contributes": {
    "commands": [
      { "command": "dracula-warm.apply", "title": "Dracula Warm: Apply Theme" }
    ],
    "keybindings": [
      { "key": "cmd+k cmd+d", "command": "dracula-warm.apply", "when": "always" }
    ]
  }
}

When the user presses the chord, the host runs the command exactly as if it were launched from the palette — including activating your extension and calling its handler if one is registered. See Commands.

5. Binding to a built-in command

command may reference a built-in Aero command, letting your extension remap existing actions. The id must match an existing command; binding to an unknown id is a no-op.

Related

• Commands — what the binding triggers.
• Manifest reference — the schema.