{"id":13571797,"url":"https://github.com/liuchengxu/vim-which-key","last_synced_at":"2025-05-14T07:08:25.833Z","repository":{"id":38856596,"uuid":"147346348","full_name":"liuchengxu/vim-which-key","owner":"liuchengxu","description":":tulip: Vim plugin that shows keybindings in popup","archived":false,"fork":false,"pushed_at":"2024-12-03T01:20:17.000Z","size":150,"stargazers_count":1954,"open_issues_count":31,"forks_count":64,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-13T13:12:32.180Z","etag":null,"topics":["neovim","space-vim","vim","vim-plugin"],"latest_commit_sha":null,"homepage":"https://liuchengxu.github.io/vim-which-key/","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liuchengxu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://www.paypal.me/liuchengxu"}},"created_at":"2018-09-04T12:58:02.000Z","updated_at":"2025-04-08T16:56:50.000Z","dependencies_parsed_at":"2023-12-16T01:29:20.659Z","dependency_job_id":"943118ea-3fe5-414a-8002-093072733a0f","html_url":"https://github.com/liuchengxu/vim-which-key","commit_stats":{"total_commits":130,"total_committers":34,"mean_commits":3.823529411764706,"dds":0.4,"last_synced_commit":"4843811d6f2104fe2140d4cddbb49352976647df"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuchengxu%2Fvim-which-key","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuchengxu%2Fvim-which-key/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuchengxu%2Fvim-which-key/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuchengxu%2Fvim-which-key/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liuchengxu","download_url":"https://codeload.github.com/liuchengxu/vim-which-key/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092776,"owners_count":22013290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["neovim","space-vim","vim","vim-plugin"],"created_at":"2024-08-01T14:01:06.479Z","updated_at":"2025-05-14T07:08:25.814Z","avatar_url":"https://github.com/liuchengxu.png","language":"Vim Script","funding_links":["https://www.paypal.me/liuchengxu"],"categories":["Vim Script"],"sub_categories":[],"readme":"# vim-which-key\n\n\u003c!-- TOC GFM --\u003e\n\n* [Introduction](#introduction)\n* [Pros.](#pros)\n* [Installation](#installation)\n    * [Plugin Manager](#plugin-manager)\n    * [Package management](#package-management)\n        * [Vim 8](#vim-8)\n        * [NeoVim](#neovim)\n* [Requirement](#requirement)\n* [Usage](#usage)\n    * [`timeoutlen`](#timeoutlen)\n    * [Special keys](#special-keys)\n    * [Configuration](#configuration)\n        * [Minimal Configuration](#minimal-configuration)\n        * [Example](#example)\n        * [Hide statusline](#hide-statusline)\n    * [Commands](#commands)\n    * [Options](#options)\n    * [FAQ](#faq)\n        * [How to map some special keys like `\u003cBS\u003e`?](#how-to-map-some-special-keys-like-bs)\n* [Credit](#credit)\n\n\u003c!-- /TOC --\u003e\n\n## Introduction\n\nvim-which-key is vim port of [emacs-which-key](https://github.com/justbur/emacs-which-key) that displays available keybindings in popup.\n\n[emacs-which-key](https://github.com/justbur/emacs-which-key) started as a rewrite of [guide-key](https://github.com/kai2nenobu/guide-key), very likely, [vim-which-key](https://github.com/liuchengxu/vim-which-key) heavily rewrote [vim-leader-guide](https://github.com/hecal3/vim-leader-guide). The features of vim-which-key has evolved a lot since then.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg width=\"800px\" src=\"https://raw.githubusercontent.com/liuchengxu/img/master/vim-which-key/vim-which-key.png\"\u003e\n    \u003cbr /\u003e\n    Vim config in the screenshot is \u003ca href=\"https://github.com/liuchengxu/space-vim\"\u003espace-vim\u003c/a\u003e.\n\u003c/p\u003e\n\n## Pros.\n\n- Better UI, vim's `popup` and neovim's `floating_win` are supported.\n- Show all mappings following a prefix, e.g., `\u003cleader\u003e`, `\u003clocalleader\u003e`, etc.\n- Instant response for your every single input.\n- Dynamic update on every call.\n- Define group names and arbitrary descriptions.\n\n## Installation\n\n### Plugin Manager\n\nAssuming you are using [vim-plug](https://github.com/junegunn/vim-plug):\n\n```vim\nPlug 'liuchengxu/vim-which-key'\n\n\" On-demand lazy load\nPlug 'liuchengxu/vim-which-key', { 'on': ['WhichKey', 'WhichKey!'] }\n\n\" To register the descriptions when using the on-demand load feature,\n\" use the autocmd hook to call which_key#register(), e.g., register for the Space key:\n\" autocmd! User vim-which-key call which_key#register('\u003cSpace\u003e', 'g:which_key_map')\n```\n\nFor other plugin managers please refer to their document for more details.\n\n### Package management\n\n#### Vim 8\n\n```bash\n$ mkdir -p ~/.vim/pack/git-plugins/start\n$ git clone https://github.com/liuchengxu/vim-which-key.git --depth=1 ~/.vim/pack/git-plugins/start/vim-which-key\n```\n\n#### NeoVim\n\n```bash\n$ mkdir -p ~/.local/share/nvim/site/pack/git-plugins/start\n$ git clone https://github.com/liuchengxu/vim-which-key.git --depth=1 ~/.local/share/nvim/site/pack/git-plugins/start/vim-which-key\n```\n\n## Requirement\n\nvim-which-key requires option `timeout` is on, see `:h timeout`.\n\nSince `timeout` is on by default, all you need is not to `set notimeout` in your `.vimrc`.\n\n## Usage\n\n### `timeoutlen`\n\nLet's say \u003ckbd\u003eSPC\u003c/kbd\u003e is your leader key and you use it to trigger vim-which-key:\n\n```vim\nnnoremap \u003csilent\u003e \u003cleader\u003e :WhichKey '\u003cSpace\u003e'\u003cCR\u003e\n```\n\nAfter pressing leader the guide buffer will pop up when there are no further keystrokes within `timeoutlen`.\n\n```vim\n\" By default timeoutlen is 1000 ms\nset timeoutlen=500\n```\n\nPressing other keys within `timeoutlen` will either complete the mapping or open a subgroup. In the screenshot above \u003ckbd\u003eSPC\u003c/kbd\u003e\u003ckbd\u003eb\u003c/kbd\u003e will open up the buffer menu.\n\nPlease note that no matter which mappings and menus you configure, your original leader mappings will remain unaffected. The key guide is an additional layer. It will only activate, when you do not complete your input during the timeoutlen duration.\n\n### Special keys\n\n- Use \u003ckbd\u003eBS\u003c/kbd\u003e to show the upper level mappings.\n\n### Configuration\n\n- For neovim, [nvim-whichkey-setup.lua](https://github.com/AckslD/nvim-whichkey-setup.lua) provides a wrapper around vim-which-key to simplify configuration in lua.\n  It also solves issues (see #126) when the mapped command is more complex and makes it easy to also map `localleader`.\n\n#### Minimal Configuration\n\n`:WhichKey` and `:WhichKeyVisual` are the primary way of interacting with this plugin.\n\nAssuming your `leader` and `localleader` key are `\u003cSpace\u003e` and `,`, respectively, even no description dictionary has been registered, all `\u003cSpace\u003e` and `,` related mappings will be displayed regardless.\n\n```vim\nlet g:mapleader = \"\\\u003cSpace\u003e\"\nlet g:maplocalleader = ','\nnnoremap \u003csilent\u003e \u003cleader\u003e      :\u003cc-u\u003eWhichKey '\u003cSpace\u003e'\u003cCR\u003e\nnnoremap \u003csilent\u003e \u003clocalleader\u003e :\u003cc-u\u003eWhichKey  ','\u003cCR\u003e\n```\n\nThe raw content displayed is normally not adequate to serve as a cheatsheet. See the following section for configuring it properly.\n\nIf no description dictionary is available, the right-hand-side of all mappings will be displayed:\n\n\u003cp align=\"center\"\u003e\u003cimg width=\"800px\" src=\"https://raw.githubusercontent.com/liuchengxu/img/master/vim-which-key/raw-spc-w.png\"\u003e\u003c/p\u003e\n\nThe dictionary configuration is necessary to provide group names or a description text:\n\n```vim\nlet g:which_key_map = {}\nlet g:which_key_map['w'] = {\n      \\ 'name' : '+windows' ,\n      \\ 'w' : ['\u003cC-W\u003ew'     , 'other-window']          ,\n      \\ 'd' : ['\u003cC-W\u003ec'     , 'delete-window']         ,\n      \\ '-' : ['\u003cC-W\u003es'     , 'split-window-below']    ,\n      \\ '|' : ['\u003cC-W\u003ev'     , 'split-window-right']    ,\n      \\ '2' : ['\u003cC-W\u003ev'     , 'layout-double-columns'] ,\n      \\ 'h' : ['\u003cC-W\u003eh'     , 'window-left']           ,\n      \\ 'j' : ['\u003cC-W\u003ej'     , 'window-below']          ,\n      \\ 'l' : ['\u003cC-W\u003el'     , 'window-right']          ,\n      \\ 'k' : ['\u003cC-W\u003ek'     , 'window-up']             ,\n      \\ 'H' : ['\u003cC-W\u003e5\u003c'    , 'expand-window-left']    ,\n      \\ 'J' : [':resize +5'  , 'expand-window-below']   ,\n      \\ 'L' : ['\u003cC-W\u003e5\u003e'    , 'expand-window-right']   ,\n      \\ 'K' : [':resize -5'  , 'expand-window-up']      ,\n      \\ '=' : ['\u003cC-W\u003e='     , 'balance-window']        ,\n      \\ 's' : ['\u003cC-W\u003es'     , 'split-window-below']    ,\n      \\ 'v' : ['\u003cC-W\u003ev'     , 'split-window-below']    ,\n      \\ '?' : ['Windows'    , 'fzf-window']            ,\n      \\ }\ncall which_key#register('\u003cSpace\u003e', \"g:which_key_map\")\n```\n\n\u003cp align=\"center\"\u003e\u003cimg width=\"800px\" src=\"https://raw.githubusercontent.com/liuchengxu/img/master/vim-which-key/spc-w.png\"\u003e\u003c/p\u003e\n\nIf you wish to hide a mapping from the menu set it's description to `'which_key_ignore'`. Useful for instance, to hide a list of \u003cleader\u003e[1-9] window swapping mappings. For example the below mapping will not be shown in the menu.\n\n```vim\nnnoremap \u003cleader\u003e1 :1wincmd w\u003cCR\u003e\nlet g:which_key_map.1 = 'which_key_ignore'\n```\n\nIf you want to hide a group of non-top level mappings, set the `name` to `'which_key_ignore'`. For example,\n\n```vim\nnnoremap \u003cleader\u003e_a :echom '_a'\u003cCR\u003e\nnnoremap \u003cleader\u003e_b :echom '_b'\u003cCR\u003e\nlet g:which_key_map['_'] = { 'name': 'which_key_ignore' }\n```\n\nIf you want to hide all mappings outside of the elements of the description dictionary, use: `let g:which_key_ignore_outside_mappings = 1`.\n\n#### Example\n\nYou can configure a Dict for each prefix so that the display is more readable.\n\nTo make the guide pop up **Register the description dictionary for the prefix first**. Assuming `Space` is your leader key and the Dict for configuring `Space` is `g:which_key_map`:\n\n```vim\nnnoremap \u003csilent\u003e \u003cleader\u003e :\u003cc-u\u003eWhichKey '\u003cSpace\u003e'\u003cCR\u003e\nvnoremap \u003csilent\u003e \u003cleader\u003e :\u003cc-u\u003eWhichKeyVisual '\u003cSpace\u003e'\u003cCR\u003e\n\ncall which_key#register('\u003cSpace\u003e', \"g:which_key_map\")\n```\n\nThe above registers the same description dictionary for both normal and visual modes. To use a separate description dictionary for each mode: add a third argument specifying which mode:\n```vim\ncall which_key#register('\u003cSpace\u003e', \"g:which_key_map\", 'n')\ncall which_key#register('\u003cSpace\u003e', \"g:which_key_map_visual\", 'v')\n```\n\nThe next step is to add items to `g:which_key_map`:\n\n```vim\n\" Define prefix dictionary\nlet g:which_key_map =  {}\n\n\" Second level dictionaries:\n\" 'name' is a special field. It will define the name of the group, e.g., leader-f is the \"+file\" group.\n\" Unnamed groups will show a default empty string.\n\n\" =======================================================\n\" Create menus based on existing mappings\n\" =======================================================\n\" You can pass a descriptive text to an existing mapping.\n\nlet g:which_key_map.f = { 'name' : '+file' }\n\nnnoremap \u003csilent\u003e \u003cleader\u003efs :update\u003cCR\u003e\nlet g:which_key_map.f.s = 'save-file'\n\nnnoremap \u003csilent\u003e \u003cleader\u003efd :e $MYVIMRC\u003cCR\u003e\nlet g:which_key_map.f.d = 'open-vimrc'\n\nnnoremap \u003csilent\u003e \u003cleader\u003eoq  :copen\u003cCR\u003e\nnnoremap \u003csilent\u003e \u003cleader\u003eol  :lopen\u003cCR\u003e\nlet g:which_key_map.o = {\n      \\ 'name' : '+open',\n      \\ 'q' : 'open-quickfix'    ,\n      \\ 'l' : 'open-locationlist',\n      \\ }\n\n\" =======================================================\n\" Create menus not based on existing mappings:\n\" =======================================================\n\" Provide commands(ex-command, \u003cPlug\u003e/\u003cC-W\u003e/\u003cC-d\u003e mapping, etc.)\n\" and descriptions for the existing mappings.\n\"\n\" Note:\n\" Some complicated ex-cmd may not work as expected since they'll be\n\" feed into `feedkeys()`, in which case you have to define a decicated\n\" Command or function wrapper to make it work with vim-which-key.\n\" Ref issue #126, #133 etc.\nlet g:which_key_map.b = {\n      \\ 'name' : '+buffer' ,\n      \\ '1' : ['b1'        , 'buffer 1']        ,\n      \\ '2' : ['b2'        , 'buffer 2']        ,\n      \\ 'd' : ['bd'        , 'delete-buffer']   ,\n      \\ 'f' : ['bfirst'    , 'first-buffer']    ,\n      \\ 'h' : ['Startify'  , 'home-buffer']     ,\n      \\ 'l' : ['blast'     , 'last-buffer']     ,\n      \\ 'n' : ['bnext'     , 'next-buffer']     ,\n      \\ 'p' : ['bprevious' , 'previous-buffer'] ,\n      \\ '?' : ['Buffers'   , 'fzf-buffer']      ,\n      \\ }\n\nlet g:which_key_map.l = {\n      \\ 'name' : '+lsp',\n      \\ 'f' : ['spacevim#lang#util#Format()'          , 'formatting']       ,\n      \\ 'r' : ['spacevim#lang#util#FindReferences()'  , 'references']       ,\n      \\ 'R' : ['spacevim#lang#util#Rename()'          , 'rename']           ,\n      \\ 's' : ['spacevim#lang#util#DocumentSymbol()'  , 'document-symbol']  ,\n      \\ 'S' : ['spacevim#lang#util#WorkspaceSymbol()' , 'workspace-symbol'] ,\n      \\ 'g' : {\n        \\ 'name': '+goto',\n        \\ 'd' : ['spacevim#lang#util#Definition()'     , 'definition']      ,\n        \\ 't' : ['spacevim#lang#util#TypeDefinition()' , 'type-definition'] ,\n        \\ 'i' : ['spacevim#lang#util#Implementation()' , 'implementation']  ,\n        \\ },\n      \\ }\n```\n\nThe guide will be up to date at all times. Native vim mappings will always take precedence over dictionary-only mappings.\n\nIt is possible to call the guide for keys other than `leader`:\n\n```vim\nnnoremap \u003clocalleader\u003e :\u003cc-u\u003eWhichKey  ','\u003cCR\u003e\nvnoremap \u003clocalleader\u003e :\u003cc-u\u003eWhichKeyVisual  ','\u003cCR\u003e\n```\n\n- Refer to [space-vim](https://github.com/liuchengxu/space-vim/blob/master/core/autoload/spacevim/map/leader.vim) for more detailed example.\n\n#### Hide statusline\n\n\u003cp align=\"center\"\u003e\u003cimg width=\"800px\" src=\"https://raw.githubusercontent.com/liuchengxu/img/master/vim-which-key/hide-statusline.png\"\u003e\u003c/p\u003e\n\nSince the theme of provided statusline is not flexible and all the information has been echoed already, I prefer to hide it.\n\n```vim\nautocmd! FileType which_key\nautocmd  FileType which_key set laststatus=0 noshowmode noruler\n  \\| autocmd BufLeave \u003cbuffer\u003e set laststatus=2 showmode ruler\n```\n\n### Commands\n\nSee more details about commands and options via `:h vim-which-key`.\n\n| Command              |                      Description                      |\n| :------------------- | :---------------------------------------------------: |\n| `:WhichKey {prefix}` |      Open the guide window for the given prefix       |\n| `:WhichKey! {dict}`  | Open the guide window for a given dictionary directly |\n\n### Options\n\n| Variable               |  Default   |                 Description                 |\n| :--------------------- | :--------: | :-----------------------------------------: |\n| `g:which_key_vertical` |     0      |            show popup vertically            |\n| `g:which_key_position` | `botright` |        split a window at the bottom         |\n| `g:which_key_hspace`   |     5      |  minimum horizontal space between columns   |\n| `g:which_key_centered` |     1      | make all keybindings centered in the middle |\n\n### FAQ\n\n#### How to map some special keys like `\u003cBS\u003e`?\n\nSee [#178](https://github.com/liuchengxu/vim-which-key/issues/178).\n\n#### How to set keybindings on filetype or other condition?\n\nYou may use BufEnter/BufLeave [#132](https://github.com/liuchengxu/vim-which-key/issues/132), a `dictionary-function` [#209](https://github.com/liuchengxu/vim-which-key/pull/209), or *[experimental]* setup per buffer [#48](https://github.com/liuchengxu/vim-which-key/pull/48).\n\n#### How to map lua functions?\n\nThis is possible via [nvim-whichkey-setup.lua](https://github.com/AckslD/nvim-whichkey-setup.lua). For example, if one wanted to map [spectre's](https://github.com/windwp/nvim-spectre) `open` to `\u003cleader\u003eS`, which in vimscipt would be `nnoremap \u003cleader\u003eS \u003ccmd\u003elua require('spectre').open()\u003cCR\u003e`, one could use the following in one's `init.vim`:\n\n```vim\nlua\u003c\u003cEOF\nlocal wk = require('whichkey_setup')\n\nlocal keymap = {\n    S = {':lua require(\"spectre\").open()\u003cCR\u003e', 'Search'},\n}\n\nwk.register_keymap('leader', keymap)\nEOF\n```\n\nNB that keymaps can only be registered once. The entirety of one's `vim-which-key` configuration must be ported to [nvim-whichkey-setup.lua](https://github.com/AckslD/nvim-whichkey-setup.lua) in order to enable this functionality.\n\n## Credit\n\n- [vim-leader-guide](https://github.com/hecal3/vim-leader-guide)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliuchengxu%2Fvim-which-key","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliuchengxu%2Fvim-which-key","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliuchengxu%2Fvim-which-key/lists"}