Master Key

Appearance

Binding Field mode ​

The mode element defines a distinct keybinding mode. Like vim modes, they affect which keybindings are currently active.

Example

toml
[[mode]]
name = "normal"
default = true
cursorShape = "Block"
highlight = "Highlight"

[[mode]]
name = "insert"
cursorShape = "Line"
highlight = "NoHighlight"
whenNoBinding = "insertCharacters"

If no keybinding modes are defined, an implicit mode is defined as follows:

toml
[[mode]]
name = "default"
default = true
cursorShape = "Line"
highlight = "NoHighlight"
whenNoBinding = "insertCharacters"

Fields ​

The only required field for a mode is its name (marked with "❗") but there are a number of optional fields that impact the behavior of the mode.

  • ❗name: The name of the mode; displayed in the bottom left corner of VSCode

  • default: whether this mode is the default when the editor is opened. There should be exactly one default mode. All keybindings without an explicit mode use this mode.

  • highlight: Whether and how to highlight the name of this mode in the bottom left corner of VSCode. Possible values are:

    • NoHighlight does not add coloring
    • Highlight adds warning related colors (usually orange)
    • Alert adds error related colors (usually red)

  • cursorShape: The shape of the cursor when in this mode. One of the following:

    • Line
    • Block
    • Underline
    • LineThin
    • BlockOutline
    • UnderlineThin

  • whenNoBinding: How to respond to keys when there is no binding for them in this mode. The options are:

    • "ignoreCharacters": The mode will introduce implicit bindings that cause any characters that are typed to be ignored. This is the default behavior when you explicitly define a mode in your file.
    • "insertCharacters": The mode defines no implicit bindings. Pressing characters will cause text to be inserted into a file, as usual. This is the default behavior for the implicitly defined "default" mode. If you define modes explicitly at least one of them must be set to "insertCharacters"; otherwise the user could not type.
    • {"useMode": "[mode]"}: fallback to the keybindings and behavior defined in another mode.
    • {"run": [<commands>]}: every character pressed is stored in key.captured. Then commands are run, as per the fields allowed when running multiple commands in [[bind]].