💥 Which Key

WhichKey helps you remember your Neovim keymaps, by showing available keybindings in a popup as you type.

✨ Features

• 🔍 Key Binding Help: show available keybindings in a popup as you type.
• ⌨️ Modes: works in normal, insert, visual, operator pending, terminal and command mode. Every mode can be enabled/disabled.
• 🛠️ Customizable Layouts: choose from classic, modern, and helix presets or customize the window.
• 🔄 Flexible Sorting: sort by local, order, group, alphanum, mod, lower, icase, desc, or manual.
• 🎨 Formatting: customizable key labels and descriptions
• 🖼️ Icons: integrates with mini.icons and nvim-web-devicons
• ⏱️ Delay: delay is independent of timeoutlen
• 🌐 Plugins: built-in plugins for marks, registers, presets, and spelling suggestions
• 🚀 Operators, Motions, Text Objects: help for operators, motions and text objects

⚡️ Requirements

• Neovim >= 0.9.0
• for proper icons support:
  • mini.icons (optional)
  • nvim-web-devicons (optional)
  • a Nerd Font (optional)

📦 Installation

Install the plugin with your package manager:

lazy.nvim

{
  "folke/which-key.nvim",
  event = "VeryLazy",
  opts = {
    -- your configuration comes here
    -- or leave it empty to use the default settings
    -- refer to the configuration section below
  },
  keys = {
    {
      "<leader>?",
      function()
        require("which-key").show({ global = false })
      end,
      desc = "Buffer Local Keymaps (which-key)",
    },
  },
}

⚙️ Configuration

[!important] Make sure to run :checkhealth which-key if something isn't working properly

WhichKey is highly configurable. Expand to see the list of all the default options below.

⌨️ Setup

WhichKey automatically gets the descriptions of your keymaps from the desc attribute of the keymap. So for most use-cases, you don't need to do anything else.

However, the mapping spec is still useful to configure group descriptions and mappings that don't really exist as a regular keymap.

[!WARNING] The mappings spec changed in v3, so make sure to only use the new add method if you updated your existing mappings.

Mappings can be added as part of the config opts.spec, or can be added later using require("which-key").add(). wk.add() can be called multiple times from anywhere in your config files.

A mapping has the following attributes:

• [1]: (string) lhs (required)
• [2]: (string|fun()) rhs (optional): when present, it will create the mapping
• desc: (string) description (required)
• mode: (string|string[]) mode (optional, defaults to "n")
• group: (string) group name (optional)
• cond: (boolean|fun():boolean) condition to enable the mapping (optional)
• hidden: (boolean) hide the mapping (optional)
• icon: (string|wk.Icon) icon spec (optional)
• any other option valid for vim.keymap.set. These are only used for creating mappings.

local wk = require("which-key")
wk.add({
  { "<leader>f", group = "file" }, -- group
  { "<leader>ff", "<cmd>Telescope find_files<cr>", desc = "Find File", mode = "n" },
  { "<leader>fb", function() print("hello") end, desc = "Foobar" },
  { "<leader>fn", desc = "New File" },
  { "<leader>f1", hidden = true }, -- hide this keymap
  {
    -- Nested mappings are allowed and can be added in any order
    -- Most attributes can be inherited or overridden on any level
    -- There's no limit to the depth of nesting
    mode = { "n", "v" }, -- NORMAL and VISUAL mode
    { "<leader>q", "<cmd>q<cr>", desc = "Quit" }, -- no need to specify mode since it's inherited
    { "<leader>w", "<cmd>w<cr>", desc = "Write" },
  }
})

🎨 Icons

[!note] For full support, you need to install either mini.icons or nvim-web-devicons

There's multiple ways to set icons for your keymaps:

• if you use lazy.nvim, then some icons will be autodetected for keymaps belonging to certain plugins.
• custom rules to decide what icon to use
• in your mapping spec, you can specify what icon to use at any level, so at the node for <leader>g for example, to apply to all git keymaps.

The icon attribute of a mapping can be a string, which will be used as the actual icon, or an wk.Icon object, which can have the following attributes:

• icon (string): the icon to use (optional)
• hl (string): the highlight group to use for the icon (optional)
• color (string): the color to use for the icon (optional) valid colors are: azure, blue, cyan, green, grey, orange, purple, red, yellow
• cat (string): the category of the icon (optional) valid categories are: file, filetype, extension
• name (string): the name of the icon in the specified category (optional)

🚀 Usage

When the WhichKey popup is open, you can use the following key bindings (they are also displayed at the bottom of the screen):

• hit one of the keys to open a group or execute a key binding
• <esc> to cancel and close the popup
• <bs> go up one level
• <c-d> scroll down
• <c-u> scroll up

🔥 Plugins

Four built-in plugins are included with WhichKey.

Presets

Built-in key binding help for motions, text-objects, operators, windows, nav, z and g and more.

Marks

Shows a list of your buffer local and global marks when you hit ` or '

Registers

Shows a list of your buffer local and global registers when you hit " in NORMAL mode, or <c-r> in INSERT mode.

Spelling

When enabled, this plugin hooks into z= and replaces the full-screen spelling suggestions window by a list of suggestions within WhichKey.

🎨 Colors

The table below shows all the highlight groups defined for WhichKey with their default link.