Skip to main content

​
Overview

CodeMirror Vim allows you to create custom key mappings using the Vim API. You can map keys in different modes (normal, insert, visual) to customize your editing experience.

​
Basic Key Mapping

Use Vim.map() to create custom key mappings: 
import { Vim } from "@replit/codemirror-vim";

// Map 'Y' to yank to end of line (like 'y$')
Vim.map("Y", "y$");

​
Mapping Keys in Different Modes

The third parameter specifies the context (mode) where the mapping applies.
1

Insert Mode Mappings

Map keys that work only in insert mode:
// Map 'jj' to escape in insert mode
Vim.map("jj", "<Esc>", "insert");
This is a popular mapping that allows you to quickly exit insert mode without reaching for the Escape key.
2

Normal Mode Mappings

Map keys for normal mode (default when no context is specified):
// Map 'Y' to yank to end of line in normal mode
Vim.map("Y", "y$");
3

Visual Mode Mappings

Create mappings specifically for visual mode:
// Custom visual mode mapping
Vim.map("<Leader>c", "gc", "visual");

​
Context Parameter

The context parameter can be one of the following:
  • "insert" - Mapping applies only in insert mode
  • "normal" - Mapping applies only in normal mode
  • "visual" - Mapping applies only in visual mode
  • Omitted - Mapping applies in normal mode by default
Context-specific mappings allow you to use the same key combination for different actions depending on the current mode.

​
Common Mapping Examples

// Popular insert mode escape sequences
Vim.map("jj", "<Esc>", "insert");
Vim.map("jk", "<Esc>", "insert");
Vim.map("kj", "<Esc>", "insert");

​
Unmapping Keys

Remove a previously defined mapping with Vim.unmap(): 
// Remove the 'jj' mapping in insert mode
Vim.unmap("jj", "insert");
Be careful when unmapping default Vim keys, as this may affect standard Vim behavior.

​
Special Key Notation

CodeMirror Vim supports Vim’s special key notation:
  • <Esc> - Escape key
  • <CR> - Enter/Return
  • <Space> - Space bar
  • <BS> - Backspace
  • <C-x> - Control + x
  • <A-x> - Alt + x
  • <S-x> - Shift + x
  • <Leader> - Leader key (if configured)
Use angle brackets <> to represent special keys, just like in Vim configuration files.

​
API Reference

​
Vim.map()

Map a key sequence to another key sequence or command. 
Vim.map(lhs: string, rhs: string, context?: string): void
Parameters:
  • lhs - Left-hand side: the key(s) to map
  • rhs - Right-hand side: the key(s) or command to execute
  • context - Optional mode context: "insert", "normal", or "visual"

​
Vim.unmap()

Remove a key mapping. 
Vim.unmap(lhs: string, context: string): void
Parameters:
  • lhs - The key(s) to unmap
  • context - The mode context where the mapping should be removed

​
Complete Example

Here’s a complete example setting up custom mappings: 
import { basicSetup, EditorView } from 'codemirror';
import { vim, Vim } from "@replit/codemirror-vim";

// Create editor
let view = new EditorView({
  doc: "",
  extensions: [
    vim(),
    basicSetup,
  ],
  parent: document.querySelector('#editor'),
});

// Set up custom mappings
Vim.map("jj", "<Esc>", "insert");  // Quick escape
Vim.map("Y", "y$");                 // Yank to end of line
Vim.map("<C-s>", ":w<CR>");         // Save shortcut (if write command defined)

Build docs developers (and LLMs) love

Get started for freeTalk to us