Home

Awesome

๐Ÿ’ฅ Which Key

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

image image image

โœจ Features

โšก๏ธ Requirements

๐Ÿ“ฆ 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.

<details><summary>Default Options</summary> <!-- config:start --> 
---@class wk.Opts
local defaults = {
  ---@type false | "classic" | "modern" | "helix"
  preset = "classic",
  -- Delay before showing the popup. Can be a number or a function that returns a number.
  ---@type number | fun(ctx: { keys: string, mode: string, plugin?: string }):number
  delay = function(ctx)
    return ctx.plugin and 0 or 200
  end,
  ---@param mapping wk.Mapping
  filter = function(mapping)
    -- example to exclude mappings without a description
    -- return mapping.desc and mapping.desc ~= ""
    return true
  end,
  --- You can add any mappings here, or use `require('which-key').add()` later
  ---@type wk.Spec
  spec = {},
  -- show a warning when issues were detected with your mappings
  notify = true,
  -- Which-key automatically sets up triggers for your mappings.
  -- But you can disable this and setup the triggers manually.
  -- Check the docs for more info.
  ---@type wk.Spec
  triggers = {
    { "<auto>", mode = "nxso" },
  },
  -- Start hidden and wait for a key to be pressed before showing the popup
  -- Only used by enabled xo mapping modes.
  ---@param ctx { mode: string, operator: string }
  defer = function(ctx)
    return ctx.mode == "V" or ctx.mode == "<C-V>"
  end,
  plugins = {
    marks = true, -- shows a list of your marks on ' and `
    registers = true, -- shows your registers on " in NORMAL or <C-r> in INSERT mode
    -- the presets plugin, adds help for a bunch of default keybindings in Neovim
    -- No actual key bindings are created
    spelling = {
      enabled = true, -- enabling this will show WhichKey when pressing z= to select spelling suggestions
      suggestions = 20, -- how many suggestions should be shown in the list?
    },
    presets = {
      operators = true, -- adds help for operators like d, y, ...
      motions = true, -- adds help for motions
      text_objects = true, -- help for text objects triggered after entering an operator
      windows = true, -- default bindings on <c-w>
      nav = true, -- misc bindings to work with windows
      z = true, -- bindings for folds, spelling and others prefixed with z
      g = true, -- bindings for prefixed with g
    },
  },
  ---@type wk.Win.opts
  win = {
    -- don't allow the popup to overlap with the cursor
    no_overlap = true,
    -- width = 1,
    -- height = { min = 4, max = 25 },
    -- col = 0,
    -- row = math.huge,
    -- border = "none",
    padding = { 1, 2 }, -- extra window padding [top/bottom, right/left]
    title = true,
    title_pos = "center",
    zindex = 1000,
    -- Additional vim.wo and vim.bo options
    bo = {},
    wo = {
      -- winblend = 10, -- value between 0-100 0 for fully opaque and 100 for fully transparent
    },
  },
  layout = {
    width = { min = 20 }, -- min and max width of the columns
    spacing = 3, -- spacing between columns
  },
  keys = {
    scroll_down = "<c-d>", -- binding to scroll down inside the popup
    scroll_up = "<c-u>", -- binding to scroll up inside the popup
  },
  ---@type (string|wk.Sorter)[]
  --- Mappings are sorted using configured sorters and natural sort of the keys
  --- Available sorters:
  --- * local: buffer-local mappings first
  --- * order: order of the items (Used by plugins like marks / registers)
  --- * group: groups last
  --- * alphanum: alpha-numerical first
  --- * mod: special modifier keys last
  --- * manual: the order the mappings were added
  --- * case: lower-case first
  sort = { "local", "order", "group", "alphanum", "mod" },
  ---@type number|fun(node: wk.Node):boolean?
  expand = 0, -- expand groups when <= n mappings
  -- expand = function(node)
  --   return not node.desc -- expand all nodes without a description
  -- end,
  -- Functions/Lua Patterns for formatting the labels
  ---@type table<string, ({[1]:string, [2]:string}|fun(str:string):string)[]>
  replace = {
    key = {
      function(key)
        return require("which-key.view").format(key)
      end,
      -- { "<Space>", "SPC" },
    },
    desc = {
      { "<Plug>%(?(.*)%)?", "%1" },
      { "^%+", "" },
      { "<[cC]md>", "" },
      { "<[cC][rR]>", "" },
      { "<[sS]ilent>", "" },
      { "^lua%s+", "" },
      { "^call%s+", "" },
      { "^:%s*", "" },
    },
  },
  icons = {
    breadcrumb = "ยป", -- symbol used in the command line area that shows your active key combo
    separator = "โžœ", -- symbol used between a key and it's label
    group = "+", -- symbol prepended to a group
    ellipsis = "โ€ฆ",
    -- set to false to disable all mapping icons,
    -- both those explicitly added in a mapping
    -- and those from rules
    mappings = true,
    --- See `lua/which-key/icons.lua` for more details
    --- Set to `false` to disable keymap icons from rules
    ---@type wk.IconRule[]|false
    rules = {},
    -- use the highlights from mini.icons
    -- When `false`, it will use `WhichKeyIcon` instead
    colors = true,
    -- used by key format
    keys = {
      Up = "๏ข ",
      Down = "๏ฃ ",
      Left = "๏  ",
      Right = "๏ก ",
      C = "๓ฐ˜ด ",
      M = "๓ฐ˜ต ",
      D = "๓ฐ˜ณ ",
      S = "๓ฐ˜ถ ",
      CR = "๓ฐŒ‘ ",
      Esc = "๓ฑŠท ",
      ScrollWheelDown = "๓ฑ• ",
      ScrollWheelUp = "๓ฑ•‘ ",
      NL = "๓ฐŒ‘ ",
      BS = "๓ฐฎ",
      Space = "๓ฑ ",
      Tab = "๓ฐŒ’ ",
      F1 = "๓ฑŠซ",
      F2 = "๓ฑŠฌ",
      F3 = "๓ฑŠญ",
      F4 = "๓ฑŠฎ",
      F5 = "๓ฑŠฏ",
      F6 = "๓ฑŠฐ",
      F7 = "๓ฑŠฑ",
      F8 = "๓ฑŠฒ",
      F9 = "๓ฑŠณ",
      F10 = "๓ฑŠด",
      F11 = "๓ฑŠต",
      F12 = "๓ฑŠถ",
    },
  },
  show_help = true, -- show a help message in the command line for using WhichKey
  show_keys = true, -- show the currently pressed key and its label as a message in the command line
  -- disable WhichKey for certain buf types and file types.
  disable = {
    ft = {},
    bt = {},
  },
  debug = false, -- enable wk.log in the current directory
}
<!-- config:end --> </details>

โŒจ๏ธ Mappings

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:

When desc, group, or icon are functions, they are evaluated every time the popup is shown.

The expand property allows to create dynamic mappings. Only functions as rhs are supported for dynamic mappings. Two examples are included in which-key.extras:

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
  { "<leader>w", proxy = "<c-w>", group = "windows" }, -- proxy to window mappings
  { "<leader>b", group = "buffers", expand = function()
      return require("which-key.extras").expand.buf()
    end
  },
  {
    -- 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" },
  }
})

๐ŸŽฏ Triggers

There's two ways that which-key can be triggered:

Both can be configured using opts.triggers and opts.defer.

By default opts.triggers includes { "<auto>", mode = "nixsotc" }, which will setup keymap triggers for every mode automatically and will trigger during ModeChanged.

[!NOTE] Auto triggers will never be created for existing keymaps. That includes every valid single key Neovim builtin mapping. If you want to trigger on a builtin keymap, you have to add it manually.

 triggers = {
   { "<auto>", mode = "nixsotc" },
   { "a", mode = { "n", "v" } },
 }

[!TIP] To manually setup triggers, you can set opts.triggers to:

 triggers = {
   { "<leader>", mode = { "n", "v" } },
 }

For ModeChanged triggers, you can configure the opts.defer option. When it returns true, the popup will be shown only after an additional key is pressed. So yaf, would show which-key after pressing ya, but not after y.

[!TIP] Defer some operators:

---@param ctx { mode: string, operator: string }
defer = function(ctx)
  if vim.list_contains({ "d", "y" }, ctx.operator) then
    return true
  end
  return vim.list_contains({ "<C-V>", "V" }, ctx.mode)
end,

๐ŸŽจ 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:

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:

[!TIP] If you'd rather not use icons, you can disable them by setting opts.icons.mappings to false.

๐Ÿš€ Usage

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

๐Ÿ™ Hydra Mode

Hydra mode is a special mode that keeps the popup open until you hit <esc>.

-- Show hydra mode for changing windows
require("which-key").show({
  keys = "<c-w>",
  loop = true, -- this will keep the popup open until you hit <esc>
})

๐Ÿ”ฅ 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 '

image

Registers

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

image

Spelling

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

image

๐ŸŽจ Colors

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

<!-- colors:start -->
Highlight GroupDefault GroupDescription
WhichKeyFunction
WhichKeyBorderFloatBorderBorder of the which-key window
WhichKeyDescIdentifierdescription
WhichKeyGroupKeywordgroup name
WhichKeyIcon@markup.linkicons
WhichKeyIconAzureFunction
WhichKeyIconBlueDiagnosticInfo
WhichKeyIconCyanDiagnosticHint
WhichKeyIconGreenDiagnosticOk
WhichKeyIconGreyNormal
WhichKeyIconOrangeDiagnosticWarn
WhichKeyIconPurpleConstant
WhichKeyIconRedDiagnosticError
WhichKeyIconYellowDiagnosticWarn
WhichKeyNormalNormalFloatNormal in th which-key window
WhichKeySeparatorCommentthe separator between the key and its description
WhichKeyTitleFloatTitleTitle of the which-key window
WhichKeyValueCommentvalues by plugins (like marks, registers, etc)
<!-- colors:end -->