• Stars
    star
    4,441
  • Rank 9,182 (Top 0.2 %)
  • Language
    Lua
  • License
    Apache License 2.0
  • Created about 3 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

πŸ’₯ Create key bindings that stick. WhichKey is a lua plugin for Neovim 0.5 that displays a popup with possible keybindings of the command you started typing.

πŸ’₯ Which Key

WhichKey is a lua plugin for Neovim 0.5 that displays a popup with possible key bindings of the command you started typing. Heavily inspired by the original emacs-which-key and vim-which-key.

image

✨ Features

  • for Neovim 0.7 and higher, it uses the desc attributes of your mappings as the default label
  • for Neovim 0.7 and higher, new mappings will be created with a desc attribute
  • opens a popup with suggestions to complete a key binding
  • works with any setting for timeoutlen, including instantly (timeoutlen=0)
  • works correctly with built-in key bindings
  • works correctly with buffer-local mappings
  • extensible plugin architecture
  • built-in plugins:
    • marks: shows your marks when you hit one of the jump keys.
    • registers: shows the contents of your registers
    • presets: built-in key binding help for motions, text-objects, operators, windows, nav, z and g
    • spelling: spelling suggestions inside the which-key popup

⚑️ Requirements

  • Neovim >= 0.5.0

πŸ“¦ Installation

Install the plugin with your preferred package manager:

lazy.nvim

{
  "folke/which-key.nvim",
  event = "VeryLazy",
  init = function()
    vim.o.timeout = true
    vim.o.timeoutlen = 300
  end,
  opts = {
    -- your configuration comes here
    -- or leave it empty to use the default settings
    -- refer to the configuration section below
  }
}

packer

-- Lua
use {
  "folke/which-key.nvim",
  config = function()
    vim.o.timeout = true
    vim.o.timeoutlen = 300
    require("which-key").setup {
      -- your configuration comes here
      -- or leave it empty to use the default settings
      -- refer to the configuration section below
    }
  end
}

βš™οΈ Configuration

❗️ IMPORTANT: the timeout when WhichKey opens is controlled by the vim setting timeoutlen. Please refer to the documentation to properly set it up. Setting it to 0, will effectively always show WhichKey immediately, but a setting of 500 (500ms) is probably more appropriate.

❗️ don't create any keymappings yourself to trigger WhichKey. Unlike with vim-which-key, we do this fully automatically. Please remove any left-over triggers you might have from using vim-which-key.

πŸš‘ You can run :checkhealth which-key to see if there's any conflicting keymaps that will prevent triggering WhichKey

WhichKey comes with the following defaults:

{
  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
    },
  },
  -- add operators that will trigger motion and text object completion
  -- to enable all native operators, set the preset / operators plugin above
  operators = { gc = "Comments" },
  key_labels = {
    -- override the label used to display some keys. It doesn't effect WK in any other way.
    -- For example:
    -- ["<space>"] = "SPC",
    -- ["<cr>"] = "RET",
    -- ["<tab>"] = "TAB",
  },
  motions = {
    count = true,
  },
  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
  },
  popup_mappings = {
    scroll_down = "<c-d>", -- binding to scroll down inside the popup
    scroll_up = "<c-u>", -- binding to scroll up inside the popup
  },
  window = {
    border = "none", -- none, single, double, shadow
    position = "bottom", -- bottom, top
    margin = { 1, 0, 1, 0 }, -- extra window margin [top, right, bottom, left]. When between 0 and 1, will be treated as a percentage of the screen size.
    padding = { 1, 2, 1, 2 }, -- extra window padding [top, right, bottom, left]
    winblend = 0, -- value between 0-100 0 for fully opaque and 100 for fully transparent
    zindex = 1000, -- positive value to position WhichKey above other floating windows.
  },
  layout = {
    height = { min = 4, max = 25 }, -- min and max height of the columns
    width = { min = 20, max = 50 }, -- min and max width of the columns
    spacing = 3, -- spacing between columns
    align = "left", -- align columns left, center or right
  },
  ignore_missing = false, -- enable this to hide mappings for which you didn't specify a label
  hidden = { "<silent>", "<cmd>", "<Cmd>", "<CR>", "^:", "^ ", "^call ", "^lua " }, -- hide mapping boilerplate
  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
  triggers = "auto", -- automatically setup triggers
  -- triggers = {"<leader>"} -- or specifiy a list manually
  -- list of triggers, where WhichKey should not wait for timeoutlen and show immediately
  triggers_nowait = {
    -- marks
    "`",
    "'",
    "g`",
    "g'",
    -- registers
    '"',
    "<c-r>",
    -- spelling
    "z=",
  },
  triggers_blacklist = {
    -- list of mode / prefixes that should never be hooked by WhichKey
    -- this is mostly relevant for keymaps that start with a native binding
    i = { "j", "k" },
    v = { "j", "k" },
  },
  -- disable the WhichKey popup for certain buf types and file types.
  -- Disabled by default for Telescope
  disable = {
    buftypes = {},
    filetypes = {},
  },
}

πŸͺ„ Setup

With the default settings, WhichKey will work out of the box for most builtin keybindings, but the real power comes from documenting and organizing your own keybindings.

To document and/or setup your own mappings, you need to call the register method

local wk = require("which-key")
wk.register(mappings, opts)

Default options for opts

{
  mode = "n", -- NORMAL mode
  -- prefix: use "<leader>f" for example for mapping everything related to finding files
  -- the prefix is prepended to every mapping part of `mappings`
  prefix = "",
  buffer = nil, -- Global mappings. Specify a buffer number for buffer local mappings
  silent = true, -- use `silent` when creating keymaps
  noremap = true, -- use `noremap` when creating keymaps
  nowait = false, -- use `nowait` when creating keymaps
  expr = false, -- use `expr` when creating keymaps
}

❕ When you specify a command in your mapping that starts with <Plug>, then we automatically set noremap=false, since you always want recursive keybindings in this case

⌨️ Mappings

⌨ for Neovim 0.7 and higher, which key will use the desc attribute of existing mappings as the default label

Group names use the special name key in the tables. There's multiple ways to define the mappings. wk.register can be called multiple times from anywhere in your config files.

local wk = require("which-key")
-- As an example, we will create the following mappings:
--  * <leader>ff find files
--  * <leader>fr show recent files
--  * <leader>fb Foobar
-- we'll document:
--  * <leader>fn new file
--  * <leader>fe edit file
-- and hide <leader>1

wk.register({
  f = {
    name = "file", -- optional group name
    f = { "<cmd>Telescope find_files<cr>", "Find File" }, -- create a binding with label
    r = { "<cmd>Telescope oldfiles<cr>", "Open Recent File", noremap=false, buffer = 123 }, -- additional options for creating the keymap
    n = { "New File" }, -- just a label. don't create any mapping
    e = "Edit File", -- same as above
    ["1"] = "which_key_ignore",  -- special label to hide it in the popup
    b = { function() print("bar") end, "Foobar" } -- you can also pass functions!
  },
}, { prefix = "<leader>" })
Click to see more examples
-- all of the mappings below are equivalent

-- method 2
wk.register({
  ["<leader>"] = {
    f = {
      name = "+file",
      f = { "<cmd>Telescope find_files<cr>", "Find File" },
      r = { "<cmd>Telescope oldfiles<cr>", "Open Recent File" },
      n = { "<cmd>enew<cr>", "New File" },
    },
  },
})

-- method 3
wk.register({
  ["<leader>f"] = {
    name = "+file",
    f = { "<cmd>Telescope find_files<cr>", "Find File" },
    r = { "<cmd>Telescope oldfiles<cr>", "Open Recent File" },
    n = { "<cmd>enew<cr>", "New File" },
  },
})

-- method 4
wk.register({
  ["<leader>f"] = { name = "+file" },
  ["<leader>ff"] = { "<cmd>Telescope find_files<cr>", "Find File" },
  ["<leader>fr"] = { "<cmd>Telescope oldfiles<cr>", "Open Recent File" },
  ["<leader>fn"] = { "<cmd>enew<cr>", "New File" },
})

Tips: The default label is keymap.desc or keymap.rhs or "", :h nvim_set_keymap() to get more details about desc and rhs.

πŸš™ Operators, Motions and Text Objects

WhichKey provides help to work with operators, motions and text objects.

[count]operator[count][text-object]

  • operators can be configured with the operators option
    • set plugins.presets.operators to true to automatically configure vim built-in operators
    • set this to false, to only include the list you configured in the operators option.
    • see here for the full list part of the preset
  • text objects are automatically retrieved from operator pending key maps (omap)
    • set plugins.presets.text_objects to true to configure built-in text objects
    • see here
  • motions are part of the preset plugins.presets.motions setting
How to disable some operators? (like v)
-- make sure to run this code before calling setup()
-- refer to the full lists at https://github.com/folke/which-key.nvim/blob/main/lua/which-key/plugins/presets/init.lua
local presets = require("which-key.plugins.presets")
presets.operators["v"] = nil

πŸš€ 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

Apart from the automatic opening, you can also manually open WhichKey for a certain prefix:

❗️ don't create any keymappings yourself to trigger WhichKey. Unlike with vim-which-key, we do this fully automatically. Please remove any left-over triggers you might have from using vim-which-key.

:WhichKey " show all mappings
:WhichKey <leader> " show all <leader> mappings
:WhichKey <leader> v " show all <leader> mappings for VISUAL mode
:WhichKey '' v " show ALL mappings for VISUAL mode

πŸ”₯ Plugins

Four built-in plugins are included with WhichKey.

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

Presets

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

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.

Highlight Group Defaults to Description
WhichKey Function the key
WhichKeyGroup Keyword a group
WhichKeySeparator DiffAdd the separator between the key and its label
WhichKeyDesc Identifier the label of the key
WhichKeyFloat NormalFloat Normal in the popup window
WhichKeyBorder FloatBorder Normal in the popup window
WhichKeyValue Comment used by plugins that provide values

More Repositories

1

lazy.nvim

πŸ’€ A modern plugin manager for Neovim
Lua
11,573
star
2

tokyonight.nvim

πŸ™ A clean, dark Neovim theme written in Lua, with support for lsp, treesitter and lots of plugins. Includes additional themes for Kitty, Alacritty, iTerm and Fish.
Lua
5,173
star
3

trouble.nvim

🚦 A pretty diagnostics, references, telescope results, quickfix and location list to help you solve all the trouble your code is causing.
Lua
4,726
star
4

noice.nvim

πŸ’₯ Highly experimental plugin that completely replaces the UI for messages, cmdline and the popupmenu.
Lua
3,677
star
5

todo-comments.nvim

βœ… Highlight, list and search todo comments in your projects
Lua
2,711
star
6

flash.nvim

Navigate your code with search labels, enhanced character motions and Treesitter integration
Lua
1,965
star
7

neodev.nvim

πŸ’» Neovim setup for init.lua and plugin development with full signature help, docs and completion for the nvim lua API.
Lua
1,935
star
8

zen-mode.nvim

🧘 Distraction-free coding for Neovim
Lua
1,442
star
9

ultra-runner

πŸƒβ›° Ultra fast monorepo script runner and build tool
TypeScript
1,188
star
10

twilight.nvim

πŸŒ… Twilight is a Lua plugin for Neovim 0.5 that dims inactive portions of the code you're editing using TreeSitter.
Lua
1,130
star
11

esbuild-runner

⚑️ Super-fast on-the-fly transpilation of modern JS, TypeScript and JSX using esbuild
TypeScript
701
star
12

dot

β˜•οΈ My Dot Files
Lua
670
star
13

edgy.nvim

Easily create and manage predefined window layouts, bringing a new edge to your workflow
Lua
665
star
14

neoconf.nvim

πŸ’Ό Neovim plugin to manage global and project-local settings
Lua
605
star
15

persistence.nvim

πŸ’Ύ Simple session management for Neovim
Lua
533
star
16

lsp-colors.nvim

🌈 Plugin that creates missing LSP diagnostics highlight groups for color schemes that don't yet support the Neovim 0.5 builtin LSP client.
Lua
434
star
17

devmoji

πŸ€– πŸš€ ✨ Emojify your conventional commits with Devmoji
TypeScript
286
star
18

styler.nvim

Simple Neovim plugin to set a different colorscheme per filetype.
Lua
247
star
19

drop.nvim

🍁 Fun little plugin that can be used as a screensaver and on your dashboard
Lua
190
star
20

polydock

✨ A shiny and hackable application dock
TypeScript
179
star
21

paint.nvim

Easily add additional highlights to your buffers
Lua
152
star
22

vscode-monorepo-workspace

πŸ“¦βœ¨Manage monorepos with multi-root workspaces. Supports Lerna, Yarn, Pnpm, Rushjs and recursive package directories.
TypeScript
138
star
23

splashcii

Simple cli tool that shows a random ascii art from https://www.asciiur.com/
TypeScript
35
star
24

semantic-release-commit-filter

πŸ“¦πŸ•΅οΈβ€β™€οΈ Semantic-release plugin that filters git commits based on the current working directory
JavaScript
25
star
25

zmk-config

Folke's ZMK config
C++
21
star
26

lovelace-styler

Custom styling for lovelace cards
TypeScript
18
star
27

folke

7
star
28

core

🏑 Open source home automation that puts local control and privacy first.
Python
5
star
29

phpintel

Accurate autocompletion / code checking / .... framework for PHP
PHP
3
star
30

adventofcode

πŸŽ… πŸŽ„ β›„ ✨ Solutions for Advent of Code 2020 in TypeScript
TypeScript
2
star
31

chess

C#
2
star
32

adventofcode2019

Advent of Code 2019 in TypeScript
TypeScript
2
star