Documentation Key Bindings

Key bindings in Sublime Text are defined by files ending in .sublime-keymap. Key bindings use JSON, with the top-level structure being an array. Each binding is a JSON object.

• Example
• Bindings
  • "keys" Key
  • "command" Key
  • "args" Key
  • "context" Key
• User Bindings

Bindings

Each key binding requires two keys, "keys" and "command". To pass args to a command, the "args" key should be specified. To restrict a key binding to a specific situation, the "context" key must be included.

"keys" Key

The "keys" value must be an array of strings, where each string contains a key press, comprised of a key and any modifiers. When multiple key presses are present in the array, the command will only be invoked if the presses are performed in sequence.

A key binding for the Escape key

{
    "keys": ["escape"],
    "command": "noop"
}

A key binding for the key A with the modifier Ctrl

{
    "keys": ["ctrl+a"],
    "command": "noop"
}

Modifiers

The following modifiers may be combined with key names for each key press.

• ctrl
• control
• alt
• option - Mac
• command - Mac
• super - the Windows key on Windows and Linux, or ⌘ on Mac
• primary - Ctrl on Windows and Linux, or ⌘ on Mac

Key Names

Key names are specified either by the (non-shifted) character printed on the key, or a key name:

"command" Key

The "command" key specifies the name of the command to execute when the key press(es) are detected. The command may be a built-in command, or a command implemented by a plugin.

{
    "keys": ["ctrl+a"],
    "command": "select_all"
}

Currently there is no compiled list of all built-in commands. The names of many commands can be found by looking at the Default ({PLATFORM_NAME}).sublime-keymap files in the Default/ package.

"args" Key

The arguments to send to the "command" key may be specified by a JSON object under the "args" key.

{
    "keys": ["primary+shift+b"],
    "command": "build",
    "args": {"select": true}
}

"context" Key

To allow for key bindings that react differently based on the situation, the "context" key allows specifying one or more conditions that must evaluate to true for the key binding to be active.

The "context" value is an array of objects. Each object must contain a "key" key that has a string value. A key is one of a predefined list of values that may be compared using an "operator" and "operand". The default operator is "equal" and the default operand is true.

For "key" values that deal with selections, an additional key "match_all" is supported. This defaults to false, which means the condition only needs to evaluate to true for a single selection. If "match_all" is true, then the condition must evaluate to true for all selections.

The following is a list of valid context "key" values:

"auto_complete_visible"

If the auto complete dropdown is visible
Valid operators: "equal", "not_equal"
Operand type: boolean

"eol_selector"

A selector to match the scope name at the end of the current line
Valid operators: "equal", "not_equal"
Operand type: string
Supports match all: yes

"following_text"

The text after the selection
Valid operators: "regex_match", "not_regex_match", "regex_contains", "not_regex_contains"
Operand type: string
Supports match all: yes

"has_next_field"

If the selection is a field in a snippet where a subsequent field exists
Valid operators: "equal", "not_equal"
Operand type: boolean

"has_prev_field"

If the selection is a field in a snippet where a previous field exists
Valid operators: "equal", "not_equal"
Operand type: boolean

"is_recording_macro"

If the user is currently recording a macro
Valid operators: "equal", "not_equal"
Operand type: boolean

"last_command"

The name of the last command that was run
Valid operators: "equal", "not_equal"
Operand type: string

"last_modifying_command"

The name of the last command run that modified a buffer
Valid operators: "equal", "not_equal"
Operand type: string

"num_selections"

The number of selection in the current buffer
Valid operators: "equal", "not_equal"
Operand type: integer

"popup_visible"

If a popup is currently being displayed
Valid operators: "equal", "not_equal"
Operand type: boolean

"preceding_text"

The text before the selection
Valid operators: "regex_match", "not_regex_match", "regex_contains", "not_regex_contains"
Operand type: string
Supports match all: yes

"read_only"

If the buffer is marked read only
Valid operators: "equal", "not_equal"
Operand type: boolean

"selection_empty"

If the current selection does not contain any characters
Valid operators: "equal", "not_equal"
Operand type: boolean
Supports match all: yes

"selector"

A selector to match the scope name of the selection
Valid operators: "equal", "not_equal"
Operand type: string
Supports match all: yes

"text"

The text of the selection
Valid operators: "regex_match", "not_regex_match", "regex_contains", "not_regex_contains"
Operand type: string
Supports match all: yes

"panel"

The name of the current panel
Valid operators: "equal", "not_equal"
Operand type: string

"panel_visible"

If a panel is visible
Valid operators: "equal", "not_equal"
Operand type: boolean

"panel_has_focus"

If a panel is visible and has focus
Valid operators: "equal", "not_equal"
Operand type: boolean

"overlay_visible"

If the quick panel is visible
Valid operators: "equal", "not_equal"
Operand type: boolean

User Bindings

Users can customize their key bindings by creating a file named Default.sublime-keymap in their Packages/User/ directory.

For example, the following will create a key binding to show unsaved changes, if any exist, via Ctrl+Shift+`.

[
    {
        "keys": ["ctrl+shift+`"],
        "command": "diff_changes"
    }
]