Vim Mode Overview

Set up and configure @replit/codemirror-vim for CodeMirror 6.

Vim Mode Overview

@replit/codemirror-vim is the primary vim emulation package for CodeMirror 6. Originally developed by Replit, it provides a comprehensive vim experience inside any CodeMirror editor, including modal editing, motions, operators, text objects, registers, macros, and Ex commands.

Installation

pnpm add @replit/codemirror-vim

Basic Setup

Add vim() to the extensions array when creating an editor.

import { EditorView, basicSetup } from "codemirror";
import { vim } from "@replit/codemirror-vim";

const view = new EditorView({
  extensions: [
    vim(),
    basicSetup,
  ],
  parent: document.getElementById("editor")!,
});

Try the vim-mode editor below. Press Escape for Normal mode, i for Insert mode, use hjkl to navigate, : for Ex commands. The status bar at the bottom shows the current mode.

vim() Function Options

The vim() function accepts an optional configuration object.

vim({
  status: true, // show a vim status indicator (mode display)
})

• status — when true, the extension includes a panel that displays the current vim mode (Normal, Insert, Visual, etc.) and partial command input

How It Works

The vim extension overrides CodeMirror’s default key handling. When a key is pressed:

• The vim layer intercepts the event before CodeMirror’s built-in keymap processing
• The key is fed into an internal vim command parser that tracks partial commands, counts, and registers
• Depending on the current mode, the parser either executes a command, transitions between modes, or passes the key through to CodeMirror

The extension maintains its own internal state for mode tracking, registers, marks, macros, and the command-line buffer. It translates vim operations into CodeMirror transactions (selections, replacements, and dispatches) to apply changes to the document.

Supported Modes

@replit/codemirror-vim supports the following vim modes:

• Normal — the default mode for navigation and issuing commands
• Insert — text input mode, entered via i, a, o, and related commands
• Visual — character-wise visual selection, entered via v
• Visual Line — line-wise visual selection, entered via V
• Visual Block — block (column) visual selection, entered via Ctrl-v
• Replace — overwrite mode, entered via R
• Command-line (Ex) — for Ex commands, entered via :

Accessing the Vim Object

Many customization APIs live on the Vim object, which is a separate import.

import { Vim } from "@replit/codemirror-vim";

This object provides methods for defining custom Ex commands, key mappings, options, and register manipulation. The following pages in this section cover each of these in detail.