Add Vim-like Which-key Popup menu

[xipeng-jin]

Closes #10910

Follow up work continuing from the last PR #42659. Add the UI element for displaying vim like which-key menu.

Screen.Recording.2025-11-26.at.2.08.22.PM.mov

Release Notes:

• Added a which-key like modal with a compact, single-column panel anchored to the bottom-right. You can enable with {"which_key": {"enabled": true}} in your settings.

[zayne-anyra]

only if vim is enable right?

[xipeng-jin]

only if vim is enable right?

Yes, vim_mode or helix_mode needs to turn on.

[claytonrcarter]

Yes, vim_mode or helix_mode needs to turn on.

This is cool! Would it be hard to support non-vim/helix mode? The are plenty of “compound” bindings in regular mode, as well as in the emacs key map, that could be exposed this way. Eg Cmd-k Cmd-s.

[mgabor3141]

For a followup, maybe a good heuristic would be to:

• Enumerate all possible actions
• Choose the binding with the fewest keys for each action and show only that.

In case of a tie, I think it's okay to show more than one keybind.

[ConradIrwin]

Amazing, thank you for this!

A few things I noticed:

• We can avoid measuring every row by rendering two columns adjacent to each other and letting taffy lay things out. (I did this, and also left-aligned the key bindings, it looked strange to me when they were right aligned).
• Sometimes the first time I trigger the menu by hitting g it is empty:

* `ctrl-w` is incorrectly still triggering the default behavior of deleting backwards despite https://github.com/zed-industries/zed/blob/a42a135750ff9130a11c8a915351bd03cc707c39/assets/keymaps/vim.json#L843 (we don't have to fix this in this PR, but would be good to figure out which change broke that and fix it in a separate PR). * That made it obvious that having a 700ms timeout for which-key, but a 1000ms timeout for "run a conflicting action" led to the menu flashing. I've fixed that by setting the default for which-key to 1000ms, so it won't show up in this case at all.

Are you able to look into why it renders empty sometimes?

[xipeng-jin]

Hi @ConradIrwin , thank you so much for your prompt review. Here is my answers for your comments:

1. Yes, I agree. I think this is a pretty smart idea to render two columns for avoiding per row measurement overhead. And left-align the key bindings would be great for consistency.

We can avoid measuring every row by rendering two columns adjacent to each other and letting taffy lay things out. (I did this, and also left-aligned the key bindings, it looked strange to me when they were right aligned).

2. I haven't encountered that issue (render empty menu) yet and look into it. Since I have been working on a follow-up PR Add customization capabilities to which-key menu #43949 on top of this and just opened it up, I am going to fully test it now to making sure we cover all the edge cases. I can remember that there are a few spots in this PR worth to have a second look. One is here https://github.com/zed-industries/zed/pull/43618/files#diff-f00679bfd9619761abc62cbb720f02d733d56cc361fb84d127600e7d464e853fR61 (I don't really like to have hard coded value FILTERED_KEYSTROKES in the code base, but this is inspired from the previous PR and it is the easy way to filter the duplicates.), the other one is https://github.com/zed-industries/zed/pull/43618/files#diff-42e0d1c722de5403e1bf675699637e42ccabaec4cae3a5eabdbf38b503ce8b37R180-R186 (This is probably the spot of the issue coming from).

Sometimes the first time I trigger the menu by hitting g it is empty:

3. There is another minor issue I noticed is about the vertical scrollbar. I don't want to trigger any scrollbar to appear and fade out (it is annoying me) for the case when the height of popup menu already fully covered all the keybindings and no need for scrolling. We should disable the scroll bar in this scenario.

BTW, if you have any extra time, can you have a quick look for my follow up PR #43949? From the high level, I am not sure that is the direction for Zed team want on the current roadmap, but having some customization/renaming capabilities would be great for next level user experiences (if not that should be great for a future PR). But like I mentioned in the parent issue #10910 (comment), that PR would be just a "add the finishing touch". Therefore, feel free to close either one of them so that we can just target one direction.

The reason why I separate the two PRs (#43949 and #43618) because the previous one #43618 already accomplish the implementation of the basic functionalities from Vim which-key like menu. That one should be the essential part, and this one is just adding the finishing touch. Therefore, it will make the team review it easier and make them easier to be prioritized.

Thanks again for taking your time here.

[avbm]

I was testing this out on my local machine and noticed that pressing <space> didn't trigger the which-key popup - however pressing g/other alphabet keys did - just FYI.

Thanks for all the work you are putting into this and really looking forward to getting this feature.

[xipeng-jin]

Hi @avbm , thanks for reporting this. However, this is not an issue with the which-key system, instead the root cause is that we have the default key mapping in zed for space to vim::WrappingRight action which will first be triggered and not showing up the menu. You need to put something like the following in your keymap.json:

  {
    "context": "(VimControl && !menu)",
    "bindings": {
      "space": null, // Disable the default action vim::WrappingRight
    },
  }

[avbm]

Yep, that did the trick - thanks.

[axelson]

I'm probably missing something obvious, but is there a guide to enabling this? I'm currently running Zed 0.217.3 which was released Dec 18th and this was merged Dec 17th, I also have vim mode enabled, but I get an error Property which_key is not allowed.

[jrmajor]

@axelson https://zed.dev/faq#what-are-the-release-channels

[saif-Fe]

@axelson https://zed.dev/faq#what-are-the-release-channels

[Wozacosta]

Yep, that did the trick - thanks.

I might be doing something wrong, but pressing <space> doesn't trigger anything. Despite having done #43618 (comment)

g / ⌘ + k open up the which-key menu.

[yannxaver]

Great contribution, thank you!

Any plans to make the position of the popup menu configurable?
Personally I would prefer it in the center of the editor.

[ggobbe]

@Wozacosta I had to remove the context for it to work for me (I also tried replacing it with helixControl w/o success)

settings.json

  "which_key": {
    "enabled": true,
    "delay_ms": 100,
  },

keymap.json

[
  {
    "bindings": {
      "space": null, // Disable the default action vim::WrappingRight
    },
  },
]

[luccahuguet]

  {
    "context": "(VimControl && !menu)",
    "bindings": {
      "space": null, // Disable the default action vim::WrappingRight
    },
  },

also works