Key Bindings

Key bindings map key presses to commands.

See Also

Official documentation for Key Bindings

File Format

Key bindings are stored in .sublime-keymap files and defined in JSON. Keymap files may be located anywhere in a package.

Naming Keymap Files

Any keymap named Default.sublime-keymap will always be applied in all platforms.

Additionally, each platform can optionally have its own keymap:

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

Sublime Text will ignore any .sublime-keymap file whose name doesn't follow the patterns just described.

Structure of a Key Binding

Keymaps are arrays of key bindings. These are all valid elements in a key binding:

keys

An array of case-sensitive keys. Modifiers can be specified with the + sign. You can build chords by adding elements to the array (for example, ["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 names of parameters to command.

context

Array of conditions that determine a particular context. All conditions must evaluate to true for the context to be active. See Structure of a Context below for more information.

Here's an example:

{ "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 the context whose value you want to query.

operator

Type of test to perform against key's value. Defaults to equal.

operand

The result returned by key is tested against this value.

match_all

Requires the test to succeed for all selections. Defaults to false.

Context Keys

Arbitrary keys may be provided by plugins. Thus, this section only features keys provided by Sublime Text itself.

auto_complete_visible

Returns true if the autocomplete list is visible.

eol_select

Selector to match scope name at end of current line

following_text

Test against the selected text and the text following it until the end of the line.

group_has_multiselect

Returns true if group has multi-select

has_next_field

Returns true if a next snippet field is available.

has_prev_field

Returns true if a previous snippet field is available.

is_javadoc

Returns true if caret(s) is (are) in a comment that starts with /**

is_recording_macro

Is user currently recording a macro?

last_command

Returns the name of the last command run.

last_modifying_command

Name of last command run that modified a buffer

num_selections

Returns the number of selections.

overlay_has_focus

Returns true if any overlay has focus.

overlay_visible

Returns true if any overlay is visible.

panel

Returns true if the panel given as operand is visible.

panel_has_focus

Returns true if a panel has input focus.

panel_visible

Returns true if any panel is visible.

popup_visible

Is a popup currently being displayed?

preceding_text

Test against the text on the line up to and including the selection.

read_only

Is buffer in read-only state?

selection_empty

Returns true if the selection is an empty region.

selector

Name of scope for current selection.

setting.x

Returns the value of the x setting. x can be any string.

text

Restricts the test to the selected text.

Context Operators

equal, not_equal

Test for equality.

regex_match, not_regex_match

Match against a regular expression (full match).

regex_contains, not_regex_contains

Match against a regular expression (partial match).

Bindable Keys

Keys in key bindings may be specified literally by symbol or by a name for a special key. Symbols cannot be combined with modifiers. For example, B will catch any key sequence inserting a B glyph, but ctrl+B is invalid and needs to be written as ctrl+shift+b instead.

Here's the list of the names for special keys:

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

Modifiers

• shift
• ctrl or control
• alt
• super (Windows: Windows key, MacOS: Command Key)
• primary (Windows: Control key, MacOS: Command Key)
• command (MacOS only)
• option (MacOS only: same as alt)

The Any Character Binding

Adding a binding for <character> (with the angled brackets and no modifiers) causes Sublime Text to bind the given command for all glyphs provided to it. You should thus only use this binding with an accompanying context filter.

The specified command will then receive an additional character argument containing the glyph that was captured.

Warning about Bindable Keys

If you're developing a package, keep this in mind:

• Ctrl+Alt+<alphanum> should never be used in any Windows key bindings.
• Option+<alphanum> should never be used in any macOS key bindings.

In both cases, the user's ability to insert non-ASCII characters would be compromised otherwise.

End-users are free to remap any key combination.

Command Mode

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

Key bindings not intended for command mode (generally, all of them) should include a context like this:

{"key": "setting.command_mode", "operand": false}

This way, plugins legitimately using command mode will be able to define appropriate key bindings without interference.

Order of Preference for Key Bindings

Key bindings in a keymap file are evaluated from the bottom to the top. The first matching context wins.

Keeping Keymaps Organized

Sublime Text ships with default keymaps under Packages/Default. Other packages may include keymap files of their own.

The recommended storage location for your personal keymap files is Packages/User.

See Also

Merging and Order of Precedence

International Keyboards

Due to the way Sublime Text maps key names to physical keys, key names may not correspond to physical keys in keyboard layouts other than US English.

Troubleshooting

To enable logging related to keymaps, see the documentation for:

• sublime.log_commands(flag)
• sublime.log_input(flag)

These may help with debugging keymaps. When a key chord does not trigger an input log, another application or your operating system is likely grabbing the key before it can reach Sublime Text.