which-key.nvim — Keybinding Helper and Popup for Neovim

Introduction

which-key.nvim is a Lua plugin for Neovim that displays a popup with possible key bindings when you start typing a key sequence. Created by folke, it has gained over 7,200 stars on GitHub and is one of the most widely adopted Neovim plugins for improving keybinding discoverability.

What which-key.nvim Does

The plugin monitors your keypress sequences in real time. When you press a prefix key and pause, it renders a floating window listing every registered mapping that begins with that prefix. Each entry shows the key, a description (if provided), and grouping labels. This turns Neovim's vast keymap space into something browsable rather than requiring pure memorization.

Architecture Overview

which-key.nvim is written entirely in Lua and hooks into Neovim's keymap system via vim.on_key. It reads mappings from Neovim's internal keymap tables and descriptions registered through vim.keymap.set. The popup uses Neovim's floating window API. Keys are organized into a tree structure for efficient prefix matching.

Self-Hosting & Configuration

which-key.nvim runs entirely within your local Neovim instance with no external dependencies. Configuration is done through a setup() call in your init.lua. Key options include: plugins.marks, plugins.registers, plugins.spelling, window.border (popup border style), layout.align, and triggers (which prefixes activate the popup). Custom group names are registered via the register() function.

Key Features

• Automatic popup showing available keybindings after a configurable delay
• Group labels to organize related mappings under descriptive headings
• Built-in display of marks, registers, and spelling suggestions
• Full support for all Neovim modes (normal, visual, operator-pending, insert)
• Customizable window appearance including position, border, and padding
• Integration with popular plugins like Telescope, LSP, and gitsigns

Comparison with Similar Tools

vim-which-key was the original Vimscript implementation inspired by Emacs which-key. which-key.nvim is a full Lua rewrite offering faster rendering and tighter Neovim integration. Compared to simply reading :map output, which-key.nvim provides contextual, real-time discovery. mini.clue from mini.nvim offers similar functionality with a more minimal footprint but fewer display customization options.

FAQ

Does it slow down normal typing? No. The popup only appears after a configurable idle delay (default 200-500ms). Normal fast typing is unaffected.

Can I hide certain mappings? Yes. You can set hidden patterns in configuration to exclude specific keys or groups from the popup.

Does it work with lazy-loaded plugins? Yes. Mappings registered after startup are picked up dynamically as plugins load.

Sources

• GitHub repository: https://github.com/folke/which-key.nvim
• Neovim documentation: :help which-key.nvim
• folke's plugin ecosystem: https://github.com/folke