Neovim for Beginners — Key Mappings and WhichKey

Configure key mappings and the WhichKey plugin.

We are going to configure a few sensible default key mappings and set up the WhichKey plugin that displays a popup with possible key bindings of the command we type.

This article is part of the Neovim for Beginners series.

The Neovim configuration files can be found in this repository.

Key Mappings

Let’s configure a few sensible key mappings using the Neovim Lua API (:h nvim_set_keymap).

Note: Check out this article for the Lua keymap APIs (:h lua-keymap).

Create a file called keymaps.lua under theafter/plugin folder.

Remember that both .vim and .lua files are loaded automatically from the runtimepath (:h rtp, :h load-plugins). Vimscript files are sourced before Lua files.

• In Insert and Terminal mode, we use jk to transition to the Normal mode.
• We always center the search results when moving back and forth.
• We map k and j to gj and gk for better lines navigation when lines wrap (:h gk, :h gj).
• We map < and > in Visual mode for better indentation. gv automatically selects the previously selected area.
• We use the black hole register “_ (:h registers) to prevent yanking the selected text during pasting in Visual mode.
• We use <Shift-h> and <Shift-l> to navigate between the previous and next buffer.
• We use <ESC> to clear the highlighted search matches.
• We use K and J to move selected lines up and down in Visual mode.
• We use the arrow keys to resize the split window.

You can add more key mappings, or change any of these key mappings to meet your preferences.

WhichKey

Nobody is going to remember all the key bindings available in Neovim. Let’s configure the WhichKey plugin to show possible key bindings of the command when we start typing.

Installation

• Firstly, let’s set timeoutlen to 300 milliseconds (default is 1000 milliseconds) in after/plugin/defaults.lua. This setting controls when or how soon WhichKey displays its popup.

-- Time in milliseconds to wait for a mapped sequence to complete.
opt.timeoutlen = 300

• In lua/plugins.lua, add the following section.

-- WhichKey
use {
   "folke/which-key.nvim",
   config = function()
     require("config.whichkey").setup()
   end,
}

• Create a file called whichkey.lua under lua/config folder with the following configuration.

• Restart Neovim and then type:PackerInstall to install the plugin.

Configuration

Now when we press the Leader key (we configure it as <Space> in after/plugin/defaults.lua), WhichKey displays a popup with the key mappings we defined.

We configure a few key mappings for

• Saving current buffer.
• Quitting Neovim.
• Closing current buffer.
• Closing all buffers except the current one.
• Commonly used packer.nvim commands.
• Opening Neogit.

Besides, when you start typing a command, WhichKey can show you the possible key bindings. There are built-in plugins for

• 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

You can further customize WhichKey to fit your preferences.

Alternatives for WhichKey that you can explore.

• legendary.nvim
• key-menu.nvim

Check out the article Learn Neovim The Practical Way for all the Vim/Neovim articles!

If you are not a Medium member yet and want to become one, click here. (A part of your subscription fee will be used to support alpha2phi.)