Settings and Keybindings
Purpose and Scope
Settings and keybindings are the main personalization surfaces that let a VS Code user turn a general-purpose editor into a working environment that matches their habits. Settings control editor, workbench, and feature behavior, while keybindings connect keyboard gestures to commands and command contexts. The product documentation describes user settings as global preferences and workspace settings as project-specific overrides stored through the Settings editor or JSON files. The repository evidence for this page focuses on the keyboard-shortcut implementation that lives inside the preferences area and on adjacent editor features that make shortcuts understandable, editable, inspectable, and usable across platforms.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts, src/vs/workbench/contrib/preferences/browser/keybindingsEditorContribution.ts
The practical problem is not only assigning a new shortcut. A user often needs to discover the command behind an action, understand whether a key is already taken, decide whether a shortcut should be conditional, and verify why a different command ran. VS Code addresses that problem with a graphical Keyboard Shortcuts editor, JSON editing support, developer inspection commands, and contextual action filtering. These pieces share the same basic vocabulary: commands, keybindings, when clauses, command categories, editor models, and services. The source files show that keyboard customization is a coordinated workbench feature rather than a single preferences dialog.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts, src/vs/workbench/contrib/codeEditor/browser/inspectKeybindings.ts
Although this page is named for settings and keybindings together, the available source evidence is much more detailed for keybindings. Read settings as the broader configuration model and keybindings as the concrete, source-backed personalization path described here. In day-to-day use, a setting may change how a feature behaves, while a keybinding changes how quickly a command can be invoked. The two meet in the Preferences experience: users can open graphical editors for discoverability, then switch to JSON when they need exact, reviewable configuration that can be versioned or synchronized.
Relevant Source Files
- src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts - Implements the workbench Keyboard Shortcuts editor surface and imports the model, search widget, define widget, action bar, context keys, keybinding service, keybinding editing service, clipboard service, telemetry, and command constants used by the UI.
- src/vs/workbench/contrib/preferences/browser/keybindingsEditorContribution.ts - Registers the keybinding-aware editor contribution for JSON editing, creates the define-keybinding overlay widget, reacts to editor model changes, and enables decorations for default and user keybindings JSON models.
- src/vs/workbench/contrib/codeEditor/browser/inspectKeybindings.ts - Registers developer commands that dump resolved keybinding information into pinned untitled editors in text or JSON form.
- src/vs/editor/contrib/codeAction/common/types.ts - Defines code-action kinds, trigger sources, auto-apply modes, filters, and filtering helpers that constrain editor actions commonly invoked from keyboard shortcuts or command surfaces.
- src/vs/editor/standalone/browser/iPadShowKeyboard/iPadShowKeyboard.ts - Registers an iOS-only standalone editor contribution that adds a writable-editor overlay widget to summon the software keyboard and disposes it when the editor becomes read-only.
- src/vs/editor/standalone/browser/iPadShowKeyboard/iPadShowKeyboard.css - Styles the iPad show-keyboard overlay, including size, placement-related affordances, light and dark keyboard icon assets, borders, and compact textarea behavior.
Core Primitives
A setting scope defines where a configuration value applies. User settings apply across VS Code windows for a person, while workspace settings apply only when a particular project or workspace is opened. The official settings documentation also describes JSON-backed storage and a graphical Settings editor, which explains why VS Code supports both approachable and precise editing paths. This distinction matters for shortcuts because keyboard shortcuts are part of a user’s working style, but they can also be affected by profiles, synchronized data, extensions, and workspace-specific expectations. Users should therefore treat shortcut editing as configuration with scope and precedence, not as a single global table.
The command is the second primitive. A keybinding maps a key gesture to a command identifier, and the Keyboard Shortcuts editor is effectively a searchable command database. The source imports command constants for defining, removing, resetting, copying, adding, clearing search results, recording search keys, defining a when clause, showing similar bindings, sorting by precedence, copying command identifiers, and copying command titles. That list reflects the real tasks users perform: they search for an action, assign a gesture, remove a mistaken override, reset to defaults, inspect related bindings, and copy exact command metadata for documentation or issue reports.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts
The when clause is the third primitive. A when clause is a conditional expression over VS Code context keys that decides whether a keybinding is active in the current UI state. The keybindings editor imports context keys for keybinding focus, the keybindings editor itself, search focus, search result state, and when-clause focus. Those context keys are important because they keep shortcuts context-sensitive without making the entire application ambiguous. The same physical key can safely mean one thing in the editor, another in the search field, and another in the keybindings table when the runtime context selects the correct rule.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts
A code action is another command-adjacent primitive because many editor shortcuts open or apply code actions. The code-action types define hierarchical categories such as quick fix, refactor, refactor extract, refactor inline, refactor move, refactor rewrite, source organize imports, source fix all, notebook, and surround with. They also define trigger sources such as lightbulb, quick fix, source action, fix all, organize imports, auto fix, save participants, and problems view. This classification explains why a keyboard shortcut can invoke a specific class of editor assistance instead of showing every possible action indiscriminately.
Sources: src/vs/editor/contrib/codeAction/common/types.ts
Keyboard Shortcuts Editor Flow
The Keyboard Shortcuts editor is implemented as a workbench editor pane backed by a model of keybinding entries. Its imports show the pieces it composes: a keybindings editor model, keybinding entry template identifier, search widget, define-keybinding widget, keybinding labels, workbench table and list infrastructure, action bars, context menus, theming, telemetry, clipboard access, and the keybinding editing service. That composition makes the UI more than a static list. It is a searchable, themed, command-aware editing surface that can present commands, display current bindings, run row actions, and persist user changes through the workbench services.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts
A typical flow starts when the user opens the Keyboard Shortcuts editor from the menu or Command Palette. The editor lists commands with and without shortcuts, and the search widget narrows the list by command text or key gesture. When the user chooses to define a binding, the define widget captures the keyboard gesture directly, which avoids forcing the user to manually spell platform-specific key names. If the result is not desired, remove and reset actions route the change through the keybinding editing service. Copy actions support debugging and sharing by exposing command identifiers or command titles in a reliable form.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts
Precedence is a major part of the user experience. Keybindings can come from defaults, extensions, keymap extensions, user overrides, and conditional rules. A user troubleshooting a surprising shortcut needs to know which rule wins, not just whether a command has a key assigned. The presence of a sort-by-precedence command and a show-similar command shows that the editor is designed for conflict analysis as well as editing. Search-state context keys and focus-specific contexts let the editor provide shortcut-specific commands only when they are meaningful, reducing accidental edits while the user is typing in the search field or when-clause input.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts
JSON Editing, Decorations, and Layout Awareness
Some users prefer the graphical Keyboard Shortcuts editor; others need the precision of JSON. Keybinding JSON can express command identifiers, key strings, when clauses, and optional arguments, so direct editing is essential for advanced review and automation. The keybinding editor contribution attaches to code editors, observes model changes, and checks whether the active model is relevant for keybinding editing. When it is relevant, it creates a decorations renderer for both the default keybindings JSON and the user keybindings JSON. That distinction is useful because the default file is a reference surface, while the user file is the override surface.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditorContribution.ts
The define-keybinding overlay widget bridges freeform JSON with safe capture. The contribution creates a DefineKeybindingOverlayWidget for the editor and exposes showDefineKeybindingWidget. When invoked on an interesting model, the widget starts, waits for an accepted keybinding, and then applies the accepted result. The imports include snippet support through SnippetController2 and SmartSnippetInserter, JSON parse-tree support, ranges, model decorations, tracked range stickiness, overview ruler colors, and native resolved keybinding types. Those dependencies indicate that the JSON path is structured editor assistance, not merely appending text to a file.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditorContribution.ts
Keyboard layout validation is a first-class concern because a syntactically valid keybinding can still be impossible to produce on the user’s current keyboard. The contribution defines a localized warning message that tells the user they will not be able to produce a key combination under the current keyboard layout. That matches the product documentation’s emphasis that displayed shortcuts follow the active keyboard layout. For contributors, the implementation lesson is direct: shortcut capture and JSON assistance must be layout-aware, because the editor should prevent unreachable shortcuts from becoming invisible configuration mistakes.
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditorContribution.ts
Compact Reference
| Surface | Concrete names | Source-level contract |
|---|---|---|
| Keyboard Shortcuts editor commands | KEYBINDINGS_EDITOR_COMMAND_DEFINE, KEYBINDINGS_EDITOR_COMMAND_REMOVE, KEYBINDINGS_EDITOR_COMMAND_RESET, KEYBINDINGS_EDITOR_COMMAND_COPY, KEYBINDINGS_EDITOR_COMMAND_COPY_COMMAND, KEYBINDINGS_EDITOR_COMMAND_COPY_COMMAND_TITLE, KEYBINDINGS_EDITOR_COMMAND_SORTBY_PRECEDENCE, KEYBINDINGS_EDITOR_COMMAND_RECORD_SEARCH_KEYS, KEYBINDINGS_EDITOR_COMMAND_DEFINE_WHEN, KEYBINDINGS_EDITOR_COMMAND_SHOW_SIMILAR, KEYBINDINGS_EDITOR_COMMAND_ADD, KEYBINDINGS_EDITOR_COMMAND_CLEAR_SEARCH_RESULTS | Imported by the workbench keybindings editor to drive row actions, search actions, definition, removal, reset, copy, precedence, similar-binding, and when-clause workflows. |
| Keyboard Shortcuts editor services | IKeybindingService, IKeybindingEditingService, IClipboardService, IContextMenuService, IContextKeyService, IEditorService, ITelemetryService | The editor pane depends on workbench services for resolving bindings, editing user keybindings, copying metadata, showing context menus, maintaining context keys, opening editors, and recording telemetry. |
| JSON contribution entry point | DEFINE_KEYBINDING_EDITOR_CONTRIB_ID, IDefineKeybindingEditorContribution, showDefineKeybindingWidget | The editor contribution registers keybinding-aware behavior and exposes a method that starts the capture overlay only for relevant keybinding JSON models. |
| Developer commands | workbench.action.inspectKeyMappings, workbench.action.inspectKeyMappingsJSON | Registered F1 developer actions that open pinned untitled editors containing keybindingService._dumpDebugInfo() or keybindingService._dumpDebugInfoJSON(). |
| Code-action taxonomy | CodeActionKind.QuickFix, Refactor, RefactorExtract, RefactorInline, RefactorMove, RefactorRewrite, Notebook, Source, SourceOrganizeImports, SourceFixAll, SurroundWith | Hierarchical action kinds used to categorize editor actions that can be triggered from command and keybinding surfaces. |
| Code-action filters | CodeActionFilter.include, excludes, includeSourceActions, onlyIncludePreferredActions; mayIncludeActionsOfKind; filtersAction | Filtering helpers reject non-intersecting kinds, honor exclusions, hide source actions unless explicitly requested, and restrict to preferred actions when requested. |
| iPad keyboard contribution | IPadShowKeyboard.ID = editor.contrib.iPadShowKeyboard; ShowKeyboardWidget.getId, getDomNode, getPosition | Registers an eventually-instantiated iOS editor contribution that adds a bottom-right textarea overlay for writable editors and focuses the editor on touch or focus. |
Sources: src/vs/workbench/contrib/preferences/browser/keybindingsEditor.ts, src/vs/workbench/contrib/preferences/browser/keybindingsEditorContribution.ts, src/vs/workbench/contrib/codeEditor/browser/inspectKeybindings.ts, src/vs/editor/contrib/codeAction/common/types.ts, src/vs/editor/standalone/browser/iPadShowKeyboard/iPadShowKeyboard.ts
Developer Inspection and Action Filtering
The repository includes two explicit developer inspection commands for keybinding diagnostics. Inspect Key Mappings and Inspect Key Mappings (JSON) are registered as Action2 classes in the Developer category and are available from F1. Their run methods obtain IKeybindingService and IEditorService, call the keybinding service’s debug dump methods, and open the resulting contents in pinned untitled editors. This is the appropriate path when a contributor or advanced user needs the resolved runtime view of keybindings rather than the editable user-facing view. It is especially useful for layout, extension, platform, and context-precedence investigations.
Sources: src/vs/workbench/contrib/codeEditor/browser/inspectKeybindings.ts
Code-action filtering shows how keyboard-triggered editor commands remain semantically scoped. The mayIncludeActionsOfKind helper checks whether a provided hierarchical kind intersects the requested include kind, applies exclusions, and blocks source actions unless source actions were explicitly requested. The filtersAction helper applies similar logic to actual language code actions and also honors onlyIncludePreferredActions. For users, this is why a shortcut for quick fixes or organize imports can produce a focused menu or direct action. For contributors, it means command and keybinding integrations should respect filters instead of bypassing the action model.
Sources: src/vs/editor/contrib/codeAction/common/types.ts
Platform and Accessibility Considerations
Keyboard configuration assumes reliable input, but not every editor instance has a physical keyboard. The standalone iPad contribution registers only when the platform is iOS. It listens for configuration changes, adds the widget only when the editor is not read-only, and disposes the widget when input is no longer allowed. The widget itself is a textarea overlay whose touchstart and focus listeners redirect focus to the editor, encouraging the operating system to show the software keyboard. This keeps the workaround narrow: it helps writable iPad editing without changing desktop keyboard behavior or exposing input controls in read-only editors.
Sources: src/vs/editor/standalone/browser/iPadShowKeyboard/iPadShowKeyboard.ts
The stylesheet keeps that platform affordance compact and theme-aware. The overlay is sized as a small button-like textarea, disables resizing and overflow, uses centered keyboard icon assets, and switches background images and border colors between the default and dark themes. That styling matters because keyboard-related UI can easily become distracting if it competes with editor content. Here the implementation preserves discoverability while keeping the control visually contained. It is also a useful example for preference-adjacent contributions: platform-specific input affordances should be conditional, disposable, positioned predictably, and styled through the editor’s theme context.
Sources: src/vs/editor/standalone/browser/iPadShowKeyboard/iPadShowKeyboard.css
Practical Guidance and Next Steps
As a user, start with the Settings editor when you are exploring available options, then move to settings JSON when you need precise, reviewable configuration. For shortcuts, start in the Keyboard Shortcuts editor, search for the command or key gesture, and use define, remove, reset, show similar, and sort by precedence before editing JSON manually. If a shortcut works in one place but not another, inspect the when clause and consider focus state, installed keymap extensions, platform defaults, keyboard layout, profile differences, and synchronized preferences. If behavior remains unclear, the Developer inspection commands expose the resolved keybinding data.
As a contributor, place changes at the layer that owns the behavior. Workbench UI changes belong near the keybindings editor pane and its widgets. JSON assistance belongs in the editor contribution that recognizes keybinding models, renders decorations, and starts the define-keybinding overlay. Runtime diagnostics belong near the inspect-keybindings actions. Editor feature shortcuts should continue to honor code-action kinds and filters, especially source actions and preferred actions. Platform input affordances should stay conditional and disposable. Read next about profiles and settings sync for cross-machine behavior, contribution points for command registration, and basic editing for editor input flows.