Skip to main content
The lua/user/keymaps.lua file defines custom key bindings that enhance navigation, editing, and window management in Neovim.

​
Overview

Keymaps are configured using vim.keymap.set with options for different modes (normal, insert, visual, etc.). The space key is set as the leader key for custom commands.

​
Leader Key Configuration

lua/user/keymaps.lua
keymap("", "<Space>", "<Nop>", opts)
vim.g.mapleader = " "
vim.g.maplocalleader = " "
The Space key is mapped as the leader key, which is used as a prefix for many custom commands throughout your configuration.

​
Keymap Options

local opts = { noremap = true, silent = true }
local term_opts = { silent = true }
  • noremap: Prevents recursive mapping
  • silent: Suppresses command output in the command line

​
Mode Reference

Keymaps are mode-specific. Understanding Neovim modes is essential for effective key binding configuration.
ModeCodeDescription
NormalnDefault mode for navigation and commands
InsertiText insertion mode
VisualvVisual selection mode
Visual BlockxVisual block selection mode
TerminaltTerminal emulator mode
CommandcCommand-line mode

​
Normal Mode Keymaps

​
Window Navigation

These keybindings allow you to navigate between split windows without using Ctrl-w first.
KeybindingActionDescription
Ctrl-h<C-w>hMove to left window
Ctrl-j<C-w>jMove to window below
Ctrl-k<C-w>kMove to window above
Ctrl-l<C-w>lMove to right window
keymap("n", "<C-h>", "<C-w>h", opts)
keymap("n", "<C-j>", "<C-w>j", opts)
keymap("n", "<C-k>", "<C-w>k", opts)
keymap("n", "<C-l>", "<C-w>l", opts)

​
Window Resizing

Use Ctrl + Arrow keys to resize split windows:
KeybindingActionDescription
Ctrl-Up:resize -2Decrease window height
Ctrl-Down:resize +2Increase window height
Ctrl-Left:vertical resize -2Decrease window width
Ctrl-Right:vertical resize +2Increase window width
keymap("n", "<C-Up>", ":resize -2<CR>", opts)
keymap("n", "<C-Down>", ":resize +2<CR>", opts)
keymap("n", "<C-Left>", ":vertical resize -2<CR>", opts)
keymap("n", "<C-Right>", ":vertical resize +2<CR>", opts)

​
Buffer Navigation

Next Buffer

Shift-l: Switch to next buffer
keymap("n", "<S-l>", ":bnext<CR>", opts)

Previous Buffer

Shift-h: Switch to previous buffer
keymap("n", "<S-h>", ":bprevious<CR>", opts)

​
Moving Lines

Quickly move lines up or down while maintaining indentation:
KeybindingActionDescription
Alt-j:m .+1<CR>==Move current line down
Alt-k:m .-2<CR>==Move current line up
keymap("n", "<A-j>", ":m .+1<CR>==", opts)
keymap("n", "<A-k>", ":m .-2<CR>==", opts)

​
Insert Mode Keymaps

​
Quick Exit

These mappings allow you to exit insert mode quickly by typing two keys in succession.
KeybindingActionDescription
jk<ESC>Exit insert mode
kj<ESC>Exit insert mode
keymap("i", "jk", "<ESC>", opts)
keymap("i", "kj", "<ESC>", opts)
These are popular alternatives to pressing the Escape key, keeping your fingers on the home row.

​
Visual Mode Keymaps

​
Indentation

These keymaps allow you to indent/outdent multiple times without losing your visual selection.
KeybindingActionDescription
<<gv^Decrease indentation and reselect
>>gv^Increase indentation and reselect
keymap("v", "<", "<gv^", opts)
keymap("v", ">", ">gv^", opts)

​
Moving Text

Move selected text up or down:
KeybindingActionDescription
Alt-j:m '>+1<CR>gv=gvMove selection down
Alt-k:m '<-2<CR>gv=gvMove selection up
keymap("v", "<A-j>", ":m '>+1<CR>gv=gv", opts)
keymap("v", "<A-k>", ":m '<-2<CR>gv=gv", opts)

​
Paste Behavior

keymap("v", "p", '"_dP', opts)
When pasting over selected text, this keeps the original yanked text in the register instead of replacing it with the deleted text.

​
Visual Block Mode Keymaps

Visual block mode allows you to select rectangular blocks of text:
KeybindingActionDescription
J:m '>+1<CR>gv=gvMove block down
K:m '<-2<CR>gv=gvMove block up
Alt-j:m '>+1<CR>gv=gvMove block down
Alt-k:m '<-2<CR>gv=gvMove block up
keymap("x", "J", ":m '>+1<CR>gv=gv", opts)
keymap("x", "K", ":m '<-2<CR>gv=gv", opts)
keymap("x", "<A-j>", ":m '>+1<CR>gv=gv", opts)
keymap("x", "<A-k>", ":m '<-2<CR>gv=gv", opts)

​
Terminal Mode Keymaps

Terminal navigation keymaps are currently commented out but available if needed.
-- Terminal navigation (commented out by default)
-- keymap("t", "<C-h>", "<C-\\><C-N><C-w>h", term_opts)
-- keymap("t", "<C-j>", "<C-\\><C-N><C-w>j", term_opts)
-- keymap("t", "<C-k>", "<C-\\><C-N><C-w>k", term_opts)
-- keymap("t", "<C-l>", "<C-\\><C-N><C-w>l", term_opts)
Uncomment these lines to enable window navigation from terminal mode.

​
Adding Custom Keymaps

1

Choose a keybinding

Select a key combination that doesn’t conflict with existing mappings.
2

Determine the mode

Decide which mode(s) the keybinding should work in (normal, insert, visual, etc.).
3

Add the mapping

Use the keymap function to create your binding:
keymap("n", "<leader>w", ":w<CR>", opts)  -- Save file with leader+w
4

Reload configuration

Save the file and restart Neovim or source the file with :luafile %.

​
Keymap Examples

keymap("n", "<leader>w", ":w<CR>", opts)

​
Best Practices

Use Leader Key

Prefix custom commands with <leader> to avoid conflicts with built-in mappings.

Be Consistent

Group related commands with similar prefixes (e.g., <leader>f for file operations).

Document Mappings

Add comments explaining what complex keybindings do.

Test Carefully

Ensure new mappings don’t override important default behavior.

​
See Also

Options

Configure editor behavior and settings

Plugins

Plugin-specific keybindings

Build docs developers (and LLMs) love

Get started for freeTalk to us