VSCode Keyboard Shortcut When Clause

Introduction

If you’ve come across the configuration panel for keyboard shortcuts in VSCode (or Cursor), you must have notices the column titled with When. This is the “when clause context” which is used to determine when a keyboard shortcut should take effect, usually assembled via context keys such as isDebugMode, editorReadonly. (In another word it is like a pre-condition if-statment for keyboard shortcut.) With this feature you can potentially have multiple command triggerable through the same keyboard shorcut depending on the active panels or states in VSCode.

Below is an official example from the VSCode documentation:

For example, VS Code uses when clauses to enable or disable command keybindings, which you can see in the Default Keybindings JSON (Preferences: Open Default Keyboard Shortcuts (JSON)):

1 2	{ "key": "f5", "command": "workbench.action.debug.start", "when": "debuggersAvailable && !inDebugMode" },

Above, the built-in “Start Debugging” command has the keyboard shortcut F5, which is only enabled when there is an appropriate debugger available (context key debuggersAvailable is true) and the editor isn’t in debug mode (context key inDebugMode is false).

Conditional Operators

The conditional operators for when clause using context keys are pretty much similar to the JavaScript conditional fashion:

• Logical Operators

  • ! (Not): Negates a condition (e.g. !editorReadonly)
  • && (And): Requires both conditions to be true (e.g. textInputFocus && !editorReadonly)
  • || (Or): Requires at least one condition to be true (e.g. isLinux || isWindows)

• Equality Operators

  • == or ===: Checks if values are equal (e.g. editorLangId == typescript)
  • != or !==: Checks if values are not equal (e.g. resourceExtname != '.js')

• Comparison Operators

  • > and >=: Greater than comparisons (e.g. gitOpenRepositoryCount >= 1)
  • < and <=: Less than comparisons (e.g. gitOpenRepositoryCount <= 5)

• Match Operator

  • =~: Allows regex matching (e.g. resourceFilename =~ /docker/)
  • Supports flags: i (case insensitive), s, m, u

• Collection Operators

  • in: Check if value exists in collection (e.g. resourceFilename in supportedFolders)
  • not in: Check if value doesn’t exist in collection (e.g. resourceFilename not in supportedFolders)

Important Notes:

• Logical operators follow a precedence order (highest to lowest): Not (!) → And (&&) → Or (||)

• Each conditional mMust include spaces around operators

  • Correct: gitOpenRepositoryCount >= 1

  • Incorrect: gitOpenRepositoryCount>=1

Use Inspect Context Key to Find When Condition

If you would like to find out the values for all the context keys for the current status. For instance:

• terminalIsOpen (is integrated terminal panel opened?)
• editorFocus(is focusing on the editor?)
• inDebugMode(is in debug mode?)
• workbenchState==workspace (is window a workspace?).

(*You can find a full list of the available context keys in the official documentation: VSCode Documentation: Available context keys)

You can check it via the “Developer: Inspect Context Key” command after running the command “Developer: Toggle Developer Tools”. This very similar to running “inspect element” after opening the developer tool using F12 in chrome when developing website.

From the above we can for instance use F2 for two distinct commands:

Reference:

https://code.visualstudio.com/api/references/when-clause-contexts#inspect-context-keys-utility