API for extensions to register display-only keybinding hints
- 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
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