microsoft / microsoft/vscode

API for extensions to register display-only keybinding hints

Open
#334,775 1 comment 0 reactions 0 assignees View on GitHub
feature-request keybindings
Dominant language
TypeScript
Stars
193k
Forks
42.4k
PR merge metrics
PR metrics pending

Description

### Problem

Extensions that implement a modal or chorded input layer (vscode-neovim, VSCodeVim,
Emacs emulations) resolve keys inside their own runtime. VS Code has no knowledge
that these bindings exist, so the Command Palette, menu items, and hover tooltips
always show the default binding, even when it is not what the user would press.

Example: with vscode-neovim, `workbench.action.quickOpen` is reachable via a
user-defined Neovim mapping (`ff`). The Command Palette shows `Ctrl+P`.
The displayed hint is not wrong, but it is not the binding the user actually uses,
and the real one is undiscoverable through the UI.

These bindings cannot be declared in `package.json` because they are defined by the
user at runtime, in the extension's own configuration format, and can change without
a reload.

### Proposed API

A display-only registration, with no effect on dispatch:

vscode.keybindings.registerHint(commandId, {
label: "space f f",
when: "neovim.mode == 'normal'"
})

VS Code would surface `label` wherever it currently renders a keybinding for that
command, when `when` evaluates true. Resolution and dispatch are untouched.

### Why existing mechanisms do not cover this

- `contributes.keybindings` is static and cannot express user-defined runtime mappings.
- Rebinding through `keybindings.json` is not viable: these are multi-key sequences
with modal context, beyond what the two-chord resolver expresses.
- #196835 (read access to keybindings) was closed as not planned, and would not
help here regardless, since the binding does not exist in VS Code's registry at all.

### Who benefits

Any extension with an internal input layer. The concrete case is modal editing
extensions, which have a large installed base and currently give users a UI that
reports bindings the user does not press.

Two things to expect: it may be closed as a duplicate of the broader dynamic-keybinding threads, and "display-only" is the load-bearing part of the pitch. If it reads as "let extensions own keybinding resolution", it gets closed immediately.

Sources:
- microsoft/vscode #196835
- microsoft/vscode #1422
- microsoft/vscode #111854
- VSpaceCode/vscode-which-key
- VSpaceCode which-key docs

Contributor guide

Open the contributing guide

Research direction

Start by reading the linked issues #196835, #1422, and #111854, then compare the existing package.json and keybindings.json mechanisms with the Command Palette, menu, and hover surfaces named here. Done means establishing whether a display-only registration can support runtime changes and conditional when clauses without affecting dispatch, while addressing the cited duplicate and feasibility concerns.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.