Which-key

​

Overview

​

What Which-key Does

• Keybinding Discovery: Shows available keybindings as you type
• Visual Organization: Groups related commands under common prefixes
• Interactive Help: Provides descriptions for each keybinding
• Timeout Management: Configurable delay before popup appears
• Learning Aid: Helps you learn and remember complex keybindings

​

Configuration

return {
  "folke/which-key.nvim",
  event = "VeryLazy",
  init = function()
    vim.o.timeout = true
    vim.o.timeoutlen = 500
  end,
  opts = {},
  config = function()
    local wk = require("which-key")
    wk.add({
      { "<leader>d", group = "Diagnostics" },
      { "<leader>e", group = "Explorer" },
      { "<leader>f", group = "Find" },
      { "<leader>l", group = "Lazy panels" },
      { "<leader>m", group = "Mason" },
      { "<leader>n", group = "NoHighlight" },
      { "<leader>p", group = "File Explorer" },
      { "<leader>s", group = "Splits" },
      { "<leader>t", group = "Tabs" },
      { "<leader>w", group = "Workspace" },
      { "<leader>x", group = "Trouble" },
    })
  end,
}

​

Configuration Details

​

Lazy Loading

event = "VeryLazy"

• Doesn’t slow down initial startup
• Loads before you need it
• Available almost immediately

​

Timeout Settings

init = function()
  vim.o.timeout = true
  vim.o.timeoutlen = 500
end

• timeout: Enables timeout for key sequences
• timeoutlen: 500ms delay before which-key popup appears

​

Keybinding Groups

wk.add({
  { "<leader>d", group = "Diagnostics" },
  { "<leader>e", group = "Explorer" },
  { "<leader>f", group = "Find" },
  { "<leader>l", group = "Lazy panels" },
  { "<leader>m", group = "Mason" },
  { "<leader>n", group = "NoHighlight" },
  { "<leader>p", group = "File Explorer" },
  { "<leader>s", group = "Splits" },
  { "<leader>t", group = "Tabs" },
  { "<leader>w", group = "Workspace" },
  { "<leader>x", group = "Trouble" },
})

​

Keybinding Groups Reference

​

<leader>d - Diagnostics

• View diagnostic messages
• Navigate between diagnostics
• Open diagnostic float
• Set diagnostic loclist

​

<leader>e - Explorer

• Toggle file explorer
• Focus file explorer
• Reveal current file
• Refresh explorer

​

<leader>f - Find

• Find files
• Find in files (grep)
• Find buffers
• Find help tags
• Find recent files
• Find git files

​

<leader>l - Lazy Panels

• Open Lazy.nvim UI
• Update plugins
• Check plugin status
• Open LazyGit

​

<leader>m - Mason

• Open Mason UI
• Install LSP servers
• Update tools
• View installed packages

​

<leader>n - NoHighlight

• Clear search highlights
• Toggle highlight on/off

​

<leader>p - File Explorer

• Toggle tree view
• Find current file
• Collapse all folders
• Expand all folders

​

<leader>s - Splits

• Split horizontally
• Split vertically
• Close split
• Resize splits
• Navigate between splits

​

<leader>t - Tabs

• New tab
• Close tab
• Next/previous tab
• Move tab
• Organize tabs

​

<leader>w - Workspace

• Add workspace folder
• Remove workspace folder
• List workspace folders
• Workspace symbols

​

<leader>x - Trouble

• Open diagnostics
• Open quickfix
• Open loclist
• Toggle Trouble panel

​

Usage

​

Discovering Keybindings

1. Press leader key: Type <leader> (usually space)
2. Wait 500ms: Which-key popup appears automatically
3. View options: See all available keybinding groups
4. Navigate: Press a letter to see that group’s commands
5. Execute: Complete the key sequence to run a command

​

Example Workflow

​

Finding Files

1. Press <space> (leader key)
2. Popup shows: f → Find, e → Explorer, etc.
3. Press f to see find commands
4. Popup shows file-finding options
5. Press the key for your desired find operation

​

Opening LazyGit

1. Press <space> (leader key)
2. Popup shows groups including l → Lazy panels
3. Press l
4. Popup shows lazy-related commands including l → LazyGit
5. Press l again to open LazyGit

​

Speedy Execution

1. Type the full sequence quickly (within 500ms)
2. Command executes without popup appearing
3. Example: <space>ff (fast) opens file finder immediately

​

Customization

​

Changing Timeout Duration

vim.o.timeoutlen = 300  -- Changed from 500 (faster popup)
-- or
vim.o.timeoutlen = 1000  -- Changed from 500 (slower popup)

• Lower value (e.g., 300): Popup appears faster (good for learning)
• Higher value (e.g., 1000): More time to type sequences (good for speed)

​

Adding New Groups

wk.add({
  { "<leader>d", group = "Diagnostics" },
  { "<leader>e", group = "Explorer" },
  -- ... existing groups ...
  { "<leader>g", group = "Git" },  -- New group
  { "<leader>r", group = "Refactor" },  -- New group
})

​

Adding Keybinding Descriptions

vim.keymap.set("n", "<leader>ff", telescope.find_files, {
  desc = "Find files",  -- Shows in which-key popup
})

​

Custom Popup Layout

opts = {
  window = {
    border = "double",  -- Border style
    position = "bottom",  -- Position on screen
    margin = { 1, 0, 1, 0 },  -- Margins
    padding = { 1, 2, 1, 2 },  -- Padding
  },
  layout = {
    height = { min = 4, max = 25 },
    width = { min = 20, max = 50 },
    spacing = 3,
  },
}

​

Disable for Specific Keys

opts = {
  plugins = {
    marks = false,  -- Disable for marks
    registers = false,  -- Disable for registers
    spelling = {
      enabled = false,  -- Disable for spelling suggestions
    },
  },
}

​

Tips and Tricks

​

Learning Keybindings

1. Press <leader> and wait
2. Read the popup to see what’s available
3. Explore each group by pressing the corresponding key
4. Use <esc> to go back or cancel

​

Speed Up Your Workflow

1. Type sequences quickly without waiting for popup
2. Common sequences become muscle memory
3. Still see popup when you forget (after 500ms)

​

Viewing All Keybindings

:WhichKey

:WhichKey <leader> n  " Normal mode, leader key
:WhichKey <leader> v  " Visual mode, leader key
:WhichKey '' i        " Insert mode, all keys

​

Creating a Reference Sheet

1. Open Neovim
2. Run :WhichKey
3. Take a screenshot or copy the display
4. Create a cheat sheet for reference

​

Mode-Specific Groups

wk.add({
  -- Normal mode (default)
  { "<leader>f", group = "Find" },
  
  -- Visual mode
  { "<leader>g", group = "Git", mode = "v" },
})

​

Nested Groups

wk.add({
  { "<leader>g", group = "Git" },
  { "<leader>gb", group = "Branches" },
  { "<leader>gc", group = "Commits" },
  { "<leader>gd", group = "Diff" },
})

​

Troubleshooting

​

Popup Not Appearing

1. Check timeout is enabled:
   :set timeout?
   
   Should return timeout
2. Check timeout length:
   :set timeoutlen?
   
   Should return timeoutlen=500
3. Verify plugin is loaded:
   :Lazy
   
   Look for which-key.nvim
4. Reload plugin:
   :Lazy reload which-key.nvim
   

​

Keybindings Not Listed

1. Check if description is provided:
   vim.keymap.set("n", "<leader>x", cmd, {
     desc = "Description here",  -- Required for which-key
   })
   
2. Verify the group is registered: Check lua/magictt/plugins/which-key.lua:11-23 for the group
3. Check keybinding was set:
   :map <leader>x
   

​

Timeout Too Fast/Slow

• Too fast (popup appears too soon): Increase timeoutlen
• Too slow (waiting too long): Decrease timeoutlen

​

Groups Not Organized

1. Add group definitions in which-key config
2. Ensure group name matches keybinding prefix
3. Reload Neovim

​

Related Configuration

• Mason - <leader>m group
• LazyGit - <leader>ll keybinding
• Telescope - <leader>f group
• Nvim-tree - <leader>e and <leader>p groups

​

External Resources

• Which-key GitHub Repository
• Which-key Documentation
• Keybinding Best Practices