when clause contexts

Visual Studio Code sets various context keys and specific values depending on what elements are visible and active in the VS Code UI. These contexts can be used to selectively enable or disable extension commands and UI elements, such as menus and views.

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)):

{ "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

A when clause can consist of a context key (for example, inDebugMode) or can use various operators to express more nuanced editor state.

Logical operators

Logical operators allow combining simple context keys or when-clause expressions that include other logical, equality, comparison, match, in/not in operators or parenthesized expressions.

Note on logical operator precedence: the above table lists operators in order of highest to lowest precedence. Examples:

Equality operators

You can check for equality of a context key's value against a specified value. Note that the right-hand side is a value and not interpreted as a context key, meaning it is not looked up in the context.

Notes:

• If the value on the right-hand side is a string containing whitespace, it must be wrapped in single-quotes - "resourceFilename == 'My New File.md'".
• === has the same behavior as ==, and !== has the same behavior as !=

Comparison operators

You can compare a context key's value against a number. Note that left- and right-hand side of the operator must be separated by whitespace - foo < 1, but not foo<1.

Match operator

(previous name: key-value pair match operator)

There is a match operator (=~) for when clauses. The expression key =~ regularExpressionLiteral treats the right-hand side as a regular expression literal to match against the left-hand side. For example, to contribute context menu items for all Docker files, one could use:

   "when": "resourceFilename =~ /docker/"

Notes:

• The right-hand side of the =~ operator follows the same rules as regular expression literals (reference) in JavaScript, except characters need to follow escaping rules both of JSON strings and regular expressions. For example, a regular expression literal to match a substring file:// would be /file:\/\// in JavaScript but /file:\\/\\// in a when clause because a backslash needs to be escaped in a JSON string and a slash needs to be escaped in the regular expression pattern.
• There does not exist an operator !=~, but you can negate the match expression - !(foo =~ /baz/).

Regular expression flags

It is possible to use flags with the regular expression literals. For example, resourceFilename =~ /json/i or myContextKey =~ /baz/si.

Supported flags: i, s, m, u.

Ignored flags: g, y.

'in' and 'not in' conditional operators

The in operator for when clauses allows for a dynamic lookup of a context key's value within another context key's value. For example, if you wanted to add a context menu command to folders that contain a certain type of file (or something that can't be statically known), you can now use the in operator to achieve it. You can use the not in operator to check the opposite condition.

First, determine which folders should support the command, and add the folder names to an array. Then, use the setContext command to turn the array into a context key:

vscode.commands.executeCommand('setContext', 'ext.supportedFolders', [
  'test',
  'foo',
  'bar'
]);

// or

// Note in this case (using an object), the value doesn't matter, it is based on the existence of the key in the object
// The value must be of a simple type
vscode.commands.executeCommand('setContext', 'ext.supportedFolders', {
  test: true,
  foo: 'anything',
  bar: false
});

Then, in the package.json you could add a menu contribution for the explorer/context menu:

// Note, this assumes you have already defined a command called ext.doSpecial
"menus": {
  "explorer/context": [
    {
      "command": "ext.doSpecial",
      "when": "explorerResourceIsFolder && resourceFilename in ext.supportedFolders"
    }
  ]
}

In that example, we are taking the value of resourceFilename (which is the name of the folder in this case) and checking for its existence in the value of ext.supportedFolders. If it exists, the menu will be shown. This powerful operator should allow for richer conditional and dynamic contributions that support when clauses, for example menus, views, etc.

Available context keys

Below are some of the available context keys, which evaluate to Boolean true/false.

The list here isn't exhaustive and you can find other when clause contexts by searching and filtering in the Keyboard Shortcuts editor (Preferences: Open Keyboard Shortcuts) or reviewing the Default Keybindings JSON file (Preferences: Open Default Keyboard Shortcuts (JSON)). You can also identify context keys you are interested in using the Inspect Context Keys utility.

Note: You can use any user or workspace setting that evaluates to a boolean here with the prefix "config.".

Visible/focused view when clause context

You can have a when clause that checks if a specific View is visible or focused.

View identifiers:

• workbench.explorer.fileView - File Explorer
• workbench.explorer.openEditorsView - Open Editors
• outline - Outline view
• timeline - Timeline view
• workbench.scm - Source Control
• workbench.scm.repositories - Source Control Repositories
• workbench.debug.variablesView - Variables
• workbench.debug.watchExpressionsView - Watch
• workbench.debug.callStackView - Call Stack
• workbench.debug.loadedScriptsView - Loaded Scripts
• workbench.debug.breakPointsView - Breakpoints
• workbench.debug.disassemblyView - Disassembly
• workbench.views.extensions.installed - Installed extensions
• extensions.recommendedList - Recommended extensions
• workbench.panel.markers.view - Problems
• workbench.panel.output - Output
• workbench.panel.repl.view - Debug Console
• terminal - Integrated Terminal
• workbench.panel.comments - Comments

Visible view container when clause context

You can have a when clause that checks if a specific View Container is visible

View container identifiers:

• workbench.view.explorer - File Explorer
• workbench.view.search - Search
• workbench.view.scm - Source Control
• workbench.view.debug - Run
• workbench.view.extensions - Extensions
• workbench.panel.markers - Problems
• workbench.panel.output - Output
• workbench.panel.repl - Debug Console
• terminal - Integrated Terminal
• workbench.panel.comments - Comments

If you want a when clause that is enabled only when a specific view container has focus, use sideBarFocus or panelFocus or auxiliaryBarFocus in combination with activeViewlet or activePanel or activeAuxiliary context keys.

For example, the when clause below is true only when the File Explorer has focus:

"sideBarFocus && activeViewlet == 'workbench.view.explorer'"

Check a setting in a when clause

In a when clause, you can reference a configuration (setting) value by prefixing it with config., for example config.editor.tabCompletion or config.breadcrumbs.enabled.

Add a custom when clause context

If you are authoring your own VS Code extension and need to enable/disable commands, menus, or views using a when clause context and none of the existing keys suit your needs, you can add your own context key with the setContext command.

The first example below sets the key myExtension.showMyCommand to true, which you can use in enablement of commands or with the when property. The second example stores a value that you could use with a when clause to check if the number of cool open things is greater than 2.

vscode.commands.executeCommand('setContext', 'myExtension.showMyCommand', true);

vscode.commands.executeCommand('setContext', 'myExtension.numberOfCoolOpenThings', 4);

Inspect Context Keys utility

If you would like to see all currently active context keys at runtime, you can use the Developer: Inspect Context Keys command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). Inspect Context Keys will display context keys and their values in the VS Code Developer Tools Console tab (Help > Toggle Developer Tools).

When you run Developer: Inspect Context Keys, your cursor will highlight elements in the VS Code UI and when you click on an element, the current context keys and their states will be output as an object to the Console.

The list of active context keys is extensive and may contain custom context keys from extensions you have installed.

Note: Some context keys are for VS Code internal use and may change in the future.