Mappings & Key Bindings

No two programmers work the same way. Some save obsessively, others navigate by search, others by marks. Vim embraces this diversity through mappings — custom key bindings that let you reshape the editor to match your habits, not the other way around. Understanding Vim's modes (see Modes & Navigation Basics) is essential here, since each mapping targets a specific mode.

This chapter shows you how to create mappings that will become second nature. We'll start with the fundamentals, work through essential mappings that most Vim users swear by, and finish with Neovim's Lua-based approach. By the end, you'll have the tools to make any keystroke do exactly what you need.

What you'll learn in this chapter:

• Create non-recursive mappings for Normal, Insert, Visual, and Command-line modes

• Configure and use the leader key as a namespace for personal key bindings

• Build practical mappings for saving, buffer navigation, line movement, and spell checking

• Define custom text objects and operator-pending mappings

• Write mappings in Neovim's Lua API with vim.keymap.set

Mapping Basics

The general form is:

{mode}map {lhs} {rhs}

Mapping Modes

Prefix	Mode	Example
nmap / nnoremap	Normal mode	nnoremap <leader>w :w<CR>
imap / inoremap	Insert mode	inoremap jk <Esc>
vmap / vnoremap	Visual mode	vnoremap < <gv
cmap / cnoremap	Command-line mode	cnoremap w!! w !sudo tee %
omap / onoremap	Operator-pending mode	onoremap il :norm vil<CR>

Tip: Always use noremap variants (e.g., nnoremap instead of nmap) to avoid recursive mapping issues.

The Leader Key

The leader key is a configurable prefix for your personal mappings:

" Vimscript
let mapleader = ' '    " space as leader

" Neovim Lua
vim.g.mapleader = ' '

Tip: Space is the most popular leader key because it's easy to press and doesn't conflict with existing mappings.

Essential Mappings

Quick Save

nnoremap <F9> :up<CR>
inoremap <F9> <C-o>:update<CR>
vnoremap <F9> :<C-u>update<CR><bar>gv

Tip: Prefer :update over :w — it only writes if the file was actually changed.

Toggle Options

" Toggle line numbers
nnoremap <leader>n :setlocal number!<CR>

" Toggle highlight search
nnoremap <leader>h :set hlsearch!<CR>

" Toggle background dark/light
nnoremap <F7> :let &bg = (&bg == "dark" ? "light" : "dark")<CR>

Toggle Search Highlighting

A more comprehensive highlight toggle that also clears manual matches:

nnoremap <silent> <leader><leader> :set hlsearch!<CR>:call clearmatches()<CR>

This clears both :hlsearch highlighting and any matches added via matchadd() or matchaddpos().

Buffer Navigation

" List and select buffers
nnoremap <leader>b :buffers<CR>:b<Space>

" Quick buffer switching
nnoremap <leader>bn :bnext<CR>
nnoremap <leader>bp :bprevious<CR>

Quickfix Navigation

nnoremap ]q :cnext<CR>
nnoremap [q :cprevious<CR>
nnoremap ]Q :clast<CR>
nnoremap [Q :cfirst<CR>

cgn Mappings

Start search-and-replace from the current word:

nnoremap c* *<C-o>cgn
nnoremap c# #<C-o>cgn

Joining Lines Without Moving Cursor

Using the Preserve function:

nnoremap J :call Preserve(':join')<CR>
nnoremap <leader>J :call Preserve(':join!')<CR>

Jump to Last Change

nnoremap gl `.

Save as Root

cnoremap w!! execute 'silent! write !sudo tee % > /dev/null' <bar> edit!

Line Text Objects

Vim doesn't have built-in line text objects, but we can create them:

" Visual mode: select a line / inner line
vnoremap <silent> al :<C-u>norm!0v$<CR>
vnoremap <silent> il :<C-u>norm!^vg_<CR>

" Operator-pending mode: use with d, y, c
onoremap <silent> al :norm val<CR>
onoremap <silent> il :norm vil<CR>

Now you can:

• yil — copy line content without newline (characterwise)

• dil — erase line content without removing the line

• dal — copy/delete the full line including leading space

Spell Checking Mappings

" Toggle spell checking
nnoremap <leader>s :setlocal spelllang=en spell! spell?<CR>

" Auto-correct last misspelled word in insert mode
inoremap <C-s> <C-g>u<Esc>[s1z=`]a<C-g>u

The <C-g>u inserts an undo-break, so you can undo the correction separately.

Spell commands:

• ]s / [s — jump to next/previous misspelled word

• z= — show suggestions

• zg — add word to dictionary

• zw — mark word as incorrect

Better Visual Mode Indenting

By default, indenting in Visual mode deselects the text. These mappings keep the selection:

vnoremap < <gv
vnoremap > >gv

Now you can press > multiple times to keep indenting without re-selecting.

Move Lines Up/Down

Move selected lines or the current line up and down:

" Normal mode
nnoremap <A-j> :m .+1<CR>==
nnoremap <A-k> :m .-2<CR>==

" Visual mode
vnoremap <A-j> :m '>+1<CR>gv=gv
vnoremap <A-k> :m '<-2<CR>gv=gv

Re-indent Entire File

Using the Preserve function to re-indent without moving the cursor:

nnoremap <leader>= :call Preserve('normal! gg=G')<CR>

Opening Config File

" Shell alias
alias ne='nvim ~/.config/nvim/init.lua'

" Vim mapping
nnoremap <silent> <leader>v :drop $MYVIMRC<CR>

Tip: :drop file opens the file in a window. If already open, it switches to that window.

Debugging Mappings

Check If a Key is Already Mapped

:verbose map <C-n>
:verbose nmap <leader>w

Vim shows the mapping and which file defined it.

Verbose map output

List All Mappings

:map        " all modes
:nmap       " normal mode
:imap       " insert mode
:vmap       " visual mode

Neovim Lua Mappings

In Neovim with Lua, use vim.keymap.set:

-- Basic mapping
vim.keymap.set('n', '<leader>w', ':update<CR>', { desc = 'Save file' })

-- With options
vim.keymap.set('n', '<leader>q', ':q<CR>', {
    noremap = true,
    silent = true,
    desc = 'Quit'
})

-- Calling a Lua function
vim.keymap.set('n', '<leader>f', function()
    print("Hello from Lua!")
end, { desc = 'Hello' })

-- Multiple modes
vim.keymap.set({'n', 'v'}, '<leader>y', '"+y', { desc = 'Copy to clipboard' })

Tip: The desc field is important — it shows up in plugins like which-key.nvim, which displays available keybindings as you type. See Chapter 11: Neovim with Lua.

Note: For a comprehensive guide to organizing your mappings and other settings in configuration files, see Configuring Vim & Neovim.

Summary

Mappings are the primary way to customize Vim's behavior and build a personalized editing environment. By binding key sequences to commands in specific modes, you can create shortcuts for frequent operations, build custom text objects, and streamline your entire workflow. Whether you use Vimscript's nnoremap or Neovim's vim.keymap.set, the principle is the same: make the editor adapt to you, not the other way around.

Key takeaways:

• Always use non-recursive mapping variants (nnoremap, inoremap, etc.) to avoid unexpected behavior from nested mappings.

• The leader key (commonly Space) provides a dedicated namespace for personal mappings that do not conflict with built-in commands.

• Mode-specific mappings let you assign different behaviors to the same key depending on whether you are in Normal, Insert, Visual, or Command-line mode.

• Use :verbose map <key> to debug mappings and discover which file defined a particular binding.

Exercises

1. Create a quick-save mapping — Map <leader>w in Normal mode to save the current file using :update. Test that it only writes when the file has actually changed.

2. Set up the leader key — Configure Space as your leader key and create three mappings: <leader>q to quit, <leader>bn to go to the next buffer, and <leader>bp to go to the previous buffer.

3. Visual mode indent mapping — Create mappings so that pressing < or > in Visual mode indents the selection without losing the visual selection. Test by selecting multiple lines and indenting them repeatedly.

4. Mode-specific escape mapping — Create a mapping that lets you press jk quickly in Insert mode to return to Normal mode. Verify that it does not interfere with typing the characters j and k slowly in sequence.

5. Debug a mapping conflict — Use :verbose nmap to list all Normal mode mappings. Find out which file defined the mapping for <C-n> (or any key of your choice). Create a new mapping that overrides it, and verify the override with :verbose map.