Vimcraft Docs / vim.keymap - Key Mapping

vim.keymap - Key Mapping

Create and manage custom keybindings with a Neovim-compatible API.

vim.keymap.set()

Create a new key mapping.

vim.keymap.set(mode, lhs, rhs, opts?)

Parameters:

mode - Mode string or array: 'n' (normal), 'i' (insert), 'v' (visual), 'x' (visual block), 's' (select), 'o' (operator-pending), 'c' (command-line), 't' (terminal)
lhs - Key sequence to map (e.g., '<leader>w', 'jk')
rhs - Command string or callback function
opts - Optional mapping options

Basic Examples

// Normal mode - save file
vim.keymap.set('n', '<leader>w', ':w<CR>', { silent: true });

// Insert mode - escape with jk
vim.keymap.set('i', 'jk', '<Esc>');

// Visual mode - yank to clipboard
vim.keymap.set('v', '<leader>y', '"+y', { desc: 'Yank to clipboard' });

// Multiple modes at once
vim.keymap.set(['n', 'v'], '<leader>/', ':noh<CR>', { silent: true });

Callback Functions

Map to JavaScript functions for complex logic:

// Custom action
vim.keymap.set('n', '<leader>ff', () => {
  console.log('Finding files...');
  // Custom file picker logic
});

// Access editor state
vim.keymap.set('n', '<leader>bd', () => {
  const buf = vim.api.getCurrentBuf();
  vim.api.bufDelete(buf, { force: false });
});

// Toggle functionality
let enabled = false;
vim.keymap.set('n', '<leader>t', () => {
  enabled = !enabled;
  console.log(`Feature ${enabled ? 'enabled' : 'disabled'}`);
});

vim.keymap.del()

Delete an existing key mapping.

vim.keymap.del(mode, lhs, opts?)

Parameters:

mode - Mode string or array
lhs - Key sequence to unmap
opts - Optional: { buffer?: boolean | number }

Examples

// Delete a global mapping
vim.keymap.del('n', '<leader>w');

// Delete a buffer-local mapping
vim.keymap.del('n', 'K', { buffer: true });

// Delete from multiple modes
vim.keymap.del(['n', 'v'], '<leader>y');

Mapping Options

interface KeymapOpts {
  noremap?: boolean;    // Non-recursive mapping (default: true)
  silent?: boolean;     // Don't echo in command line
  expr?: boolean;       // Evaluate rhs as expression
  buffer?: boolean | number;  // Buffer-local mapping
  nowait?: boolean;     // Don't wait for longer mappings
  unique?: boolean;     // Error if mapping exists
  desc?: string;        // Description (shown in :map)
  callback?: () => void;  // Alternative to function rhs
}

Option Examples

// Silent mapping (no command echo)
vim.keymap.set('n', '<leader>w', ':w<CR>', { silent: true });

// Buffer-local mapping (current buffer only)
vim.keymap.set('n', 'gd', gotoDefinition, { buffer: true });

// With description for discoverability
vim.keymap.set('n', '<leader>ff', findFiles, {
  desc: 'Find files in project'
});

// Expression mapping
vim.keymap.set('i', '<Tab>', () => {
  return vim.fn.pumvisible() ? '<C-n>' : '<Tab>';
}, { expr: true });

Mode Reference

Mode	Character	Description
Normal	`'n'`	Default navigation mode
Insert	`'i'`	Text input mode
Visual	`'v'`	Character-wise selection
Visual Block	`'x'`	Block selection
Select	`'s'`	Selection mode (typing replaces)
Operator-pending	`'o'`	After operator, awaiting motion
Command-line	`'c'`	Ex command input (`:`, `/`, `?`)
Terminal	`'t'`	Terminal emulator mode
All	`''`	All modes

Special Keys

Common special key notations:

Notation	Key
`<CR>`	Enter
`<Esc>`	Escape
`<Tab>`	Tab
`<Space>`	Space
`<leader>`	Leader key (default: `\`)
`<C-x>`	Ctrl+x
`<A-x>` or `<M-x>`	Alt+x
`<S-x>`	Shift+x