Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 36 ยท Configuration and Plugins

Mappings and the Leader Key

Create your own Vim shortcuts: map vs noremap, per-mode mapping commands, the leader key, special keys like <CR> and <Cmd>, timeouts, abbreviations and debugging.

A mapping tells Vim: "when I type these keys in this mode, act as if I had typed those keys instead." Mappings are the most common reason people edit their vimrc. They are also an easy place to go wrong, so this lesson covers the safe form first.

The basic form

VIM
nnoremap <leader>w :write<CR>

Read it left to right: normal mode, norecursive (do not re-map the result), map. The first key sequence is the left-hand side (what you type), the rest is the right-hand side (what Vim does). <CR> is the Enter key, so the mapping types :write and presses Enter.

One command per mode

Command Mode
nnoremap Normal
inoremap Insert
vnoremap Visual and Select
xnoremap Visual only
onoremap Operator-pending (after d, y, c...)
cnoremap Command line
tnoremap Terminal
noremap Normal, Visual, Select and Operator-pending

Without nore (nmap, imap...) the right-hand side is itself subject to mappings. This is recursive and is almost never what you want. If you map j to gj with nmap j gj, Vim expands gj again, and since g or j may also be mapped, you can end up in a loop or with surprises. Always use the noremap forms unless you deliberately want a mapping to call another one (plugins sometimes do, with <Plug> names).

JS Stand-in: remap versus noremap

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The leader key

<leader> is a placeholder for a prefix key you choose, so your own shortcuts do not collide with built-in ones. The default is backslash, which is far to reach; most people use Space or comma:

VIM
let mapleader = " "
let maplocalleader = ","

Set mapleader before the mappings that use it, because <leader> is replaced at the moment the mapping is defined. <localleader> is the same idea for mappings that only apply to certain file types.

Examples:

VIM
nnoremap <leader>w :write<CR>
nnoremap <leader>q :quit<CR>
nnoremap <leader>h :nohlsearch<CR>
nnoremap <leader>ev :edit $MYVIMRC<CR>
nnoremap <leader>sv :source $MYVIMRC<CR>

Special keys

Write keys in angle brackets: <CR>, <Esc>, <Tab>, <Space>, <BS>, <C-w> (Ctrl-w), <A-j> or <M-j> (Alt-j), <S-Tab>, <F5>, <Bar> (for |). Capital or lowercase inside the brackets does not matter for names.

Mapping modifiers, written right after the command name:

  • <silent>: do not echo the command, nnoremap <silent> <leader>h :nohlsearch<CR>.
  • <buffer>: the mapping only exists in the current buffer.
  • <expr>: the right-hand side is an expression that is evaluated.
  • <nowait>: do not wait to see if a longer mapping follows.
  • <Cmd>: in the right-hand side, runs a command without changing mode and without flashing the command line: nnoremap <leader>w <Cmd>write<CR>. It is more robust than :, especially in Neovim and for visual mode mappings.

Useful examples

VIM
" Move by display lines when text wraps
nnoremap j gj
nnoremap k gk

" Keep the selection after indenting in visual mode
xnoremap < <gv
xnoremap > >gv

" Jump between windows with Ctrl-h/j/k/l
nnoremap <C-h> <C-w>h
nnoremap <C-j> <C-w>j
nnoremap <C-k> <C-w>k
nnoremap <C-l> <C-w>l

" Make Y behave like D and C (yank to end of line)
nnoremap Y y$

" Escape from insert with jk
inoremap jk <Esc>

The jk mapping works because Vim waits for the second key. Your typing speed matters: if you type j and nothing follows within timeoutlen (default 1000 ms), Vim inserts j. A shorter timeout (set timeoutlen=400) makes ambiguous prefixes snappier.

Prefix conflicts and timeouts

If you define both <leader>w and <leader>wq, typing <leader>w makes Vim wait for the next key, so the shorter mapping is delayed. Avoid mappings where one is the start of another, or use <nowait> for buffer-local ones.

JS Stand-in: pick a mapping with prefix rules

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Inspecting and removing mappings

  • :nmap lists normal-mode mappings; :nmap <leader> lists those starting with the leader.
  • :verbose nmap <leader>w shows where it was defined, which finds conflicts with plugins.
  • :nunmap <leader>w removes one; :mapclear removes all.
  • :map flags: * marks a non-recursive mapping, & marks one that only remaps script-local keys, and @ marks a buffer-local mapping.

Abbreviations

An abbreviation expands when you type a non-keyword character after it:

VIM
iabbrev teh the
iabbrev @@ [email protected]
cabbrev W w

iabbrev works in insert mode, cabbrev in the command line. Unlike a mapping, an abbreviation only triggers on whole words.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you prefer nnoremap over nmap?

    Recursive mappings expand the right-hand side again. Non-recursive ones use built-in meanings.
  2. 2. When must let mapleader be set?

    <leader> is substituted when the mapping is defined, so the variable must already hold your chosen key.
  3. 3. What does <Cmd>write<CR> do compared with :write<CR>?

    <Cmd> runs an Ex command directly from a mapping, which is more reliable in visual and operator-pending modes.
  4. 4. How do you find where a mapping was defined?

    :verbose followed by a map listing shows the script and line that set it.

Summary

  • A mapping has a mode, a left-hand side and a right-hand side: nnoremap {lhs} {rhs}.
  • Use the non-recursive noremap forms; use <Cmd> for command mappings.
  • Set mapleader first; keep your shortcuts under <leader>.
  • <silent>, <buffer>, <expr> and <nowait> change how a mapping behaves.
  • Debug with :nmap and :verbose; use iabbrev for text expansion.

Next: Autocommands and Vim Script