This guide is deprecated. New content at docs.sublimetext.info

Key Bindings

Key bindings map key presses to commands.

File Format

Key bindings are stored in .sublime-keymap files and defined in JSON. All key map file names need to follow this pattern: Default (<platform>).sublime-keymap. Otherwise, Sublime Text will ignore them.

Platform-Specific Key Maps

Each platform gets its own key map:

  • Default (Windows).sublime-keymap
  • Default (OSX).sublime-keymap
  • Default (Linux).sublime-keymap

Separate key maps exist to abide by different vendor-specific HCI guidelines.

Structure of a Key Binding

Key maps are arrays of key bindings. Below you’ll find valid elements in key bindings.

keys
An array of case-sensitive keys to be pressed. Modifiers can be specified with the + sign. Chords are built by adding elements to the array, e. g. ["ctrl+k","ctrl+j"]. Ambiguous chords are resolved with a timeout.
command
Name of the command to be executed.
args
Dictionary of arguments to be passed to command. Keys must be the names of parameters to command.
context
Array of contexts to selectively enable the key binding. All contexts must be true for the key binding to trigger. See Structure of a Context below.

Here’s an example illustrating most of the features outlined above:

{ "keys": ["shift+enter"], "command": "insert_snippet", "args": {"contents": "\n\t$0\n"}, "context":
        [
                { "key": "setting.auto_indent", "operator": "equal", "operand": true },
                { "key": "selection_empty", "operator": "equal", "operand": true, "match_all": true },
                { "key": "preceding_text", "operator": "regex_contains", "operand": "\\{$", "match_all": true },
                { "key": "following_text", "operator": "regex_contains", "operand": "^\\}", "match_all": true }
        ]
}

Structure of a Context

key
Name of a context operand to query.
operator
Type of test to perform against key.
operand
Value against which the result of key is tested.
match_all
Requires the test to succeed for all selections. Defaults to false.

Context Operands

auto_complete_visible
Returns true if the autocomplete list is visible.
has_next_field
Returns true if there’s a next snippet field available.
has_prev_field
Returns true if there’s a previous snippet field available.
num_selections
Returns the number of selections.
overlay_visible
Returns true if any overlay is visible.
panel_visible
Returns true if any panel is visible.
following_text
Restricts the test to the text following the caret.
preceding_text
Restricts the test to the text preceding the caret.
selection_empty
Returns true if the selection is an empty region.
setting.x
Returns the value of the x setting. x can be any string.
text
Restricts the test to the line the caret is in.
selector
Returns the current scope.

Context Operators

equal, not_equal
Test for equality.
regex_match, not_regex_match
Match against a regular expression.
regex_contains, not_regex_contains
Match against a regular expression (containment).

Command Mode

Sublime Text provides a command_mode setting to prevent key presses from being sent to the buffer. This is useful to emulate Vim’s modal behavior.

Bindable Keys

Keys may be specified literally or by name. Below you’ll find the list of valid names:

  • up
  • down
  • right
  • left
  • insert
  • home
  • end
  • pageup
  • pagedown
  • backspace
  • delete
  • tab
  • enter
  • pause
  • escape
  • space
  • keypad0
  • keypad1
  • keypad2
  • keypad3
  • keypad4
  • keypad5
  • keypad6
  • keypad7
  • keypad8
  • keypad9
  • keypad_period
  • keypad_divide
  • keypad_multiply
  • keypad_minus
  • keypad_plus
  • keypad_enter
  • clear
  • f1
  • f2
  • f3
  • f4
  • f5
  • f6
  • f7
  • f8
  • f9
  • f10
  • f11
  • f12
  • f13
  • f14
  • f15
  • f16
  • f17
  • f18
  • f19
  • f20
  • sysreq
  • break
  • context_menu
  • browser_back
  • browser_forward
  • browser_refresh
  • browser_stop
  • browser_search
  • browser_favorites
  • browser_home

Modifiers

  • shift
  • ctrl
  • alt
  • super (Windows key, Command key…)

Warning about Bindable Keys

  • Ctrl+Alt+<alphanum> should not be used on any Windows key bindings.
  • Option+<alphanum> should not be used on any OS X key bindings.

In both cases, the users ability to insert non-ascii characters would be compromised.

Keeping Key Maps Organized

Sublime Text ships with default key maps under Packages/Default. Other packages may include their own key map files. The recommended storage location for your personal key map is Packages/User.

See Merging and Order of Preference for information about how Sublime Text sorts files for merging.

International Keyboards

Due to the way Sublime Text maps key names to physical keys, there might be a mismatch between the two.

Troubleshooting

See sublime.log_commands(flag) to enable command logging. It may help when debugging key maps.