Jay Taylor's notes

back to listing index

liuchengxu/vim-which-key

[web search]
Original source (github.com)
Tags: vim github.com
Clipped on: 2018-09-05
Vim plugin that shows keybindings in popup

README.md

vim-which-key

Introduction

vim-which-key is vim port of emacs-which-key that displays available keybindings in popup.

emacs-which-key started as a rewrite of guide-key, very likely, vim-which-key heavily rewrote vim-leader-guide with a goal of going further in vim world. The features of vim-which-key has evolved a lot since then.

Pros.

  • Show all mappings following a prefix, e.g., <leader>, <localleader>, etc.
  • Instant response for your every single input.
  • Dynamic update on every call.
  • Define group names and arbitrary descriptions.

Installation

Plugin Manager

Assuming you are using vim-plug:

Plug 'liuchengxu/vim-which-key'

" On-demand lazy load
Plug 'liuchengxu/vim-which-key', { 'on': ['WhichKey', 'WhichKey!'] }

For other plugin managers please refer to their document for more details.

Package management

Vim 8

$ mkdir -p ~/.vim/pack/git-plugins/start
$ git clone https://github.com/liuchengxu/vim-which-key.git --depth=1 ~/.vim/pack/git-plugins/start/vim-which-key

NeoVim

$ mkdir -p ~/.local/share/nvim/site/pack/git-plugins/start
$ git clone https://github.com/liuchengxu/vim-which-key.git --depth=1 ~/.local/share/nvim/site/pack/git-plugins/start/vim-which-key

Requirement

vim-which-key requires option timeout is on, see :h timeout.

Since timeout is on by default, all you need is not to set notimeout in your .vimrc.

Usage

timeoutlen

Let's say SPC is your leader key and you use it to trigger vim-which-key:

nnoremap <silent> <leader> :WhichKey '<Space>'<CR>

After pressing leader the guide buffer will pop up when there are no further keystrokes within timeoutlen.

" By default timeoutlen is 1000 ms
set timeoutlen=500

Pressing other keys within timeoutlen will either complete the mapping or open a subgroup. In the screenshot above SPCb will open up the buffer menu.

Please 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.

Configuration

Miminal Configuration

If no description dictionary is available, the right-handle-side of all mappings will be displayed:

nnoremap <silent> <leader> :<c-u>WhichKey '<Space>'<CR>

However, the dictionary configuration is necessary to provide group names or a description text.

let g:which_key_map['w'] = {
      \ 'name' : '+windows' ,
      \ 'w' : ['<C-W>w'     , 'other-window']          ,
      \ 'd' : ['<C-W>c'     , 'delete-window']         ,
      \ '-' : ['<C-W>s'     , 'split-window-below']    ,
      \ '|' : ['<C-W>v'     , 'split-window-right']    ,
      \ '2' : ['<C-W>v'     , 'layout-double-columns'] ,
      \ 'h' : ['<C-W>h'     , 'window-left']           ,
      \ 'j' : ['<C-W>j'     , 'window-below']          ,
      \ 'l' : ['<C-W>l'     , 'window-right']          ,
      \ 'k' : ['<C-W>k'     , 'window-up']             ,
      \ 'H' : ['<C-W>5<'    , 'expand-window-left']    ,
      \ 'J' : ['resize +5'  , 'expand-window-below']   ,
      \ 'L' : ['<C-W>5>'    , 'expand-window-right']   ,
      \ 'K' : ['resize -5'  , 'expand-window-up']      ,
      \ '=' : ['<C-W>='     , 'balance-window']        ,
      \ 's' : ['<C-W>s'     , 'split-window-below']    ,
      \ 'v' : ['<C-W>v'     , 'split-window-below']    ,
      \ '?' : ['Windows'    , 'fzf-window']            ,
      \ }

Example

Refer to space-vim for more detailed example.

" Define prefix dictionary
let g:which_key_map =  {}

" Second level dictionaries:
" 'name' is a special field. It will define the name of the group.
" leader-f is the "+file" group.
" Unnamed groups will show a default string
let g:which_key_map.f = { 'name' : '+file' }

nnoremap <silent> <leader>fs :update<CR>
let g:which_key_map.f.s = ['update', 'save-file']

" Provide commands and descriptions for existing mappings
" command, <Plug>/<C-W>/<C-d> mapping are supported
nnoremap <silent> <leader>fd :e $MYVIMRC<CR>
let g:which_key_map.f.d = ['e $MYVIMRC', 'open-vimrc']

let g:which_key_map.o = { 'name' : '+open' }

nnoremap <silent> <leader>oq  :copen<CR>
let g:which_key_map.o.q = ['copen', 'open-quickfix']

nnoremap <silent> <leader>ol  :lopen<CR>
let g:which_key_map.o.l = ['lopen', 'open-locationlist']

" Create new menus not based on existing mappings:
let g:which_key_map.b = {
      \ 'name' : '+buffer' ,
      \ '1' : ['b1'        , 'buffer 1']        ,
      \ '2' : ['b2'        , 'buffer 2']        ,
      \ 'd' : ['bd'        , 'delete-buffer']   ,
      \ 'f' : ['bfirst'    , 'first-buffer']    ,
      \ 'h' : ['Startify'  , 'home-buffer']     ,
      \ 'l' : ['blast'     , 'last-buffer']     ,
      \ 'n' : ['bnext'     , 'next-buffer']     ,
      \ 'p' : ['bprevious' , 'previous-buffer'] ,
      \ '?' : ['Buffers'   , 'fzf-buffer']      ,
      \ }

let g:which_key_map.l = {
      \ 'name' : '+lsp'                                            ,
      \ 'f' : ['LanguageClient#textDocument_formatting()'     , 'formatting']       ,
      \ 'h' : ['LanguageClient#textDocument_hover()'          , 'hover']            ,
      \ 'r' : ['LanguageClient#textDocument_references()'     , 'references']       ,
      \ 'R' : ['LanguageClient#textDocument_rename()'         , 'rename']           ,
      \ 's' : ['LanguageClient#textDocument_documentSymbol()' , 'document-symbol']  ,
      \ 'S' : ['LanguageClient#workspace_symbol()'            , 'workspace-symbol'] ,
      \ 'g' : {
        \ 'name': '+goto',
        \ 'd' : ['LanguageClient#textDocument_definition()'     , 'definition']       ,
        \ 't' : ['LanguageClient#textDocument_typeDefinition()' , 'type-definition']  ,
        \ 'i' : ['LanguageClient#textDocument_implementation()'  , 'implementation']   ,
        \ },
      \ }

To make the guide pop up Register the description dictionary for the prefix first (assuming Space is your leader key):

call which_key#register('<Space>', "g:which_key_map")
nnoremap <silent> <leader> :<c-u>WhichKey '<Space>'<CR>
vnoremap <silent> <leader> :<c-u>WhichKeyVisual '<Space>'<CR>

The guide will be up to date at all times. Native vim mappings will always take precedence over dictionary-only mappings.

It is possible to call the guide for keys other than leader:

nnoremap <localleader> :<c-u>WhichKey  ','<CR>
vnoremap <localleader> :<c-u>WhichKeyVisual  ','<CR>

Hide statusline

Since the theme of provided statusline is not flexible and all the information has been echoed already, I prefer to hide it.

autocmd! FileType which_key
autocmd  FileType which_key set laststatus=0 noshowmode noruler
  \| autocmd BufLeave <buffer> set laststatus=2 showmode ruler

Commands

See more details about commands and options via :h vim-which-key.

Command Description
:WhichKey {prefix} Open the guide window for the given prefix
:WhichKey! {dict} Open the guide window for a given dictionary directly

Options

Variable Default Description
g:which_key_vertical 0 show popup vertically
g:which_key_position botright split a window at the bottom
g:which_key_hspace 5 minimum horizontal space between columns

Credit

Press h to open a hovercard with more details.