Skip to main content

​
Overview

Which-Key displays a popup with possible keybindings after you start typing a command, making it easy to discover and remember shortcuts. Plugin: which-key.nvim Config File: lua/user/whichkey.lua

​
Features

  • Popup showing available keybindings
  • Organized command groups
  • Built-in help for marks, registers, and spelling
  • Customizable window and icons
  • Automatic trigger after timeout

​
Quick Start

Press <leader> (space by default) and wait briefly. A popup will appear showing all available keybindings starting with the leader key.

​
Leader Key Mappings

All mappings use <leader> as the prefix (typically <Space>).

​
Top-Level Shortcuts

KeyCommandDescription
<leader>aAlphaOpen dashboard
<leader>bBuffersTelescope buffer picker
<leader>eExplorerToggle NvimTree
<leader>wSaveWrite current file
<leader>qQuitQuit Neovim
<leader>cClose BufferClose current buffer
<leader>hNo HighlightClear search highlighting
<leader>fFind filesTelescope file finder
<leader>FFind TextLive grep search
<leader>PProjectsTelescope projects

​
Packer Commands (<leader>p)

KeyCommandDescription
<leader>pcPackerCompileCompile plugin configs
<leader>piPackerInstallInstall plugins
<leader>psPackerSyncSync plugins
<leader>pSPackerStatusShow plugin status
<leader>puPackerUpdateUpdate plugins

​
Git Commands (<leader>g)

KeyCommandDescription
<leader>ggLazygitOpen Lazygit
<leader>gjNext HunkJump to next git hunk
<leader>gkPrev HunkJump to previous hunk
<leader>glBlameShow git blame
<leader>gpPreview HunkPreview git changes
<leader>grReset HunkReset current hunk
<leader>gRReset BufferReset entire buffer
<leader>gsStage HunkStage current hunk
<leader>guUndo Stage HunkUndo staging
<leader>goOpen changed fileTelescope git status
<leader>gbCheckout branchTelescope git branches
<leader>gcCheckout commitTelescope git commits
<leader>gdDiffShow diff against HEAD

​
LSP Commands (<leader>l)

KeyCommandDescription
<leader>laCode ActionShow code actions
<leader>ldDocument DiagnosticsShow buffer diagnostics
<leader>lwWorkspace DiagnosticsShow all diagnostics
<leader>lfFormatFormat current buffer
<leader>liInfoShow LSP info
<leader>lIInstaller InfoShow LSP installer info
<leader>ljNext DiagnosticJump to next diagnostic
<leader>lkPrev DiagnosticJump to previous diagnostic
<leader>llCodeLens ActionRun code lens
<leader>lqQuickfixAdd to quickfix list
<leader>lrRenameRename symbol
<leader>lsDocument SymbolsTelescope document symbols
<leader>lSWorkspace SymbolsTelescope workspace symbols

​
Search Commands (<leader>s)

KeyCommandDescription
<leader>sbCheckout branchTelescope git branches
<leader>scColorschemeBrowse color schemes
<leader>shFind HelpSearch help tags
<leader>sMMan PagesSearch man pages
<leader>srOpen Recent FileTelescope old files
<leader>sRRegistersShow registers
<leader>skKeymapsSearch keymaps
<leader>sCCommandsSearch commands

​
Terminal Commands (<leader>t)

KeyCommandDescription
<leader>tnNodeOpen Node REPL
<leader>tuNCDUOpen disk usage analyzer
<leader>ttHtopOpen system monitor
<leader>tpPythonOpen Python REPL
<leader>tfFloatFloating terminal
<leader>thHorizontalHorizontal terminal
<leader>tvVerticalVertical terminal

​
Plugin Configuration

​
Built-in Helpers

Which-Key provides automatic help for: 
plugins = {
  marks = true,        -- Shows marks on ' and `
  registers = true,    -- Shows registers on " or <C-r>
  spelling = {
    enabled = true,    -- Shows suggestions on z=
    suggestions = 20,  -- Number of suggestions
  },
  presets = {
    operators = false, -- Help for d, y, c operators
    motions = true,    -- Help for motions
    text_objects = true, -- Help for text objects
    windows = true,    -- Help for <C-w> commands
    nav = true,        -- Help for navigation
    z = true,          -- Help for z commands
    g = true,          -- Help for g commands
  },
}

​
Window Style

window = {
  border = "rounded",           -- Window border style
  position = "bottom",          -- Position on screen
  margin = { 1, 0, 1, 0 },     -- Margins [top, right, bottom, left]
  padding = { 2, 2, 2, 2 },    -- Padding [top, right, bottom, left]
  winblend = 0,                 -- Transparency
}

​
Layout

layout = {
  height = { min = 4, max = 25 },  -- Window height
  width = { min = 20, max = 50 },  -- Window width
  spacing = 3,                      -- Spacing between columns
  align = "left",                   -- Column alignment
}

​
Icons

icons = {
  breadcrumb = "»",  -- Symbol in command line
  separator = "➜",   -- Between key and label
  group = "+",       -- Prefix for groups
}

popup_mappings = {
  scroll_down = "<c-d>",  -- Scroll down in popup
  scroll_up = "<c-u>",    -- Scroll up in popup
}

​
Trigger Behavior

triggers = "auto",  -- Automatically setup triggers
-- Or specify manually:
-- triggers = {"<leader>"}

​
Blacklisted Triggers

Prevents Which-Key from triggering on certain keys: 
triggers_blacklist = {
  i = { "j", "k" },  -- Don't trigger on j/k in insert mode
  v = { "j", "k" },  -- Don't trigger on j/k in visual mode
}

​
Customization

​
Add Custom Mappings

Add your own keybinding groups: 
local mappings = {
  -- ... existing mappings ...
  
  d = {
    name = "Debug",
    b = { "<cmd>lua require'dap'.toggle_breakpoint()<cr>", "Breakpoint" },
    c = { "<cmd>lua require'dap'.continue()<cr>", "Continue" },
    s = { "<cmd>lua require'dap'.step_over()<cr>", "Step Over" },
  },
}

​
Change Window Position

window = {
  border = "rounded",
  position = "top",  -- Move to top of screen
}

​
Change Border Style

Available styles: "none", "single", "double", "shadow", "rounded" 
window = {
  border = "double",
}

​
Show Operator Help

Enable preset for operators (d, y, c, etc.): 
presets = {
  operators = true,  -- Show help for d, y, c
}

​
Custom Key Labels

Override key display names: 
key_labels = {
  ["<space>"] = "SPC",
  ["<cr>"] = "RET",
  ["<tab>"] = "TAB",
}

​
Ignore Missing Labels

ignore_missing = false,  -- Show warning for mappings without labels

​
Hide Implementation Details

hidden = { "<silent>", "<cmd>", "<Cmd>", "<CR>", "call", "lua", "^:", "^ " }

​
Usage Tips

​
Discover Commands

  1. Press <leader> and wait
  2. See all available top-level commands
  3. Press a group key (e.g., g for Git)
  4. See all commands in that group

​
Learn Keybindings

Which-Key helps you learn keybindings by showing:
  • What keys are available
  • What each key does
  • Organized groups of related commands

​
Built-in Help

Try these to see Which-Key’s built-in helpers:
  • Press ' to see marks
  • Press " to see registers
  • Press z= for spelling suggestions
  • Press <C-r> in insert mode for registers
  • Keymaps - Basic keybinding configuration
  • Telescope - Many commands use Telescope
  • LSP - LSP command group
  • Gitsigns - Git command group

Build docs developers (and LLMs) love

Get started for freeTalk to us