@vimee/plugin-codemirror

Attach vim editing to any CodeMirror 6 EditorView

Framework-agnostic plugin that adds vim keybindings to a CodeMirror 6 EditorView. Works with vanilla JS, React, or any CodeMirror wrapper.

Install

npm install @vimee/core @vimee/plugin-codemirror

Note: You also need @codemirror/state and @codemirror/view as peer dependencies in your project.

Quick Start

import { EditorView, basicSetup } from "codemirror";
import { javascript } from "@codemirror/lang-javascript";
import { attach } from "@vimee/plugin-codemirror";

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

const vim = attach(view, {
  onChange: (value) => console.log("Content:", value),
  onModeChange: (mode) => console.log("Mode:", mode),
  onSave: (value) => console.log("Saved:", value),
});

// Later...
vim.destroy();

API

attach(view, options?)

Attaches vim keybindings to a CodeMirror 6 EditorView. Returns a VimCodeMirror handle.

The view parameter accepts any object satisfying the CodeMirrorView interface — typically a @codemirror/view EditorView.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | readOnly | boolean | false | Read-only mode (motions work, edits blocked) | | onChange | (value: string) => void | — | Content change callback | | onModeChange | (mode: VimMode) => void | — | Mode change callback | | onYank | (text: string) => void | — | Yank callback | | onSave | (value: string) => void | — | :w callback | | onAction | (action: VimAction, key: string) => void | — | Action callback | | indentStyle | "space" \| "tab" | "space" | Indent character | | indentWidth | number | 2 | Spaces per indent |

VimCodeMirror

| Method | Return | Description | |--------|--------|-------------| | getMode() | VimMode | Current vim mode | | getCursor() | CursorPosition | Current cursor position (0-based) | | getContent() | string | Current editor content | | destroy() | void | Detach all listeners and clean up |

Search Highlighting

While typing a search pattern ( /query or ?query ), the plugin highlights all matching ranges using a CodeMirror decoration with the CSS class vimee-search-match . The highlight is removed when the search is confirmed with <CR> .

A default yellow background theme is included via EditorView.baseTheme() . To customize the style, add a higher-specificity rule or use a CodeMirror theme extension:

/* Override via CSS */
.cm-editor .vimee-search-match {
  background-color: rgba(255, 120, 0, 0.4);
}

// Override via CodeMirror theme extension
import { EditorView } from "@codemirror/view";

const myTheme = EditorView.theme({
  ".vimee-search-match": {
    backgroundColor: "rgba(255, 120, 0, 0.4)",
  },
});

const view = new EditorView({
  extensions: [basicSetup, javascript(), myTheme],
  // ...
});

Visual Mode

The plugin uses CodeMirror's native selection for visual and visual-line mode. Visual-block mode creates per-line selection ranges for proper rectangular selection via EditorSelection .

To customize the selection color, use a CodeMirror theme extension:

const myTheme = EditorView.theme({
  "&.cm-focused .cm-selectionBackground, .cm-selectionBackground": {
    backgroundColor: "rgba(255, 165, 0, 0.3) !important",
  },
});

const view = new EditorView({
  extensions: [basicSetup, javascript(), myTheme],
  // ...
});

Features

• Visual mode selection (including visual-block with per-line ranges)
• Incremental search highlighting ( / / ? )
• H/M/L motions with viewport tracking
• Ctrl-U/D/B/F page scrolling
• IME composition support (CJK input)
• All vim features from @vimee/core (motions, operators, text objects, search, macros, marks, etc.)

Utilities

The package also exports cursor and viewport utilities for advanced usage:

import {
  cursorToOffset, // Convert vimee CursorPosition (0-based line/col) → character offset
  offsetToCursor, // Convert character offset → vimee CursorPosition (0-based)
  getTopLine,     // Get first visible line (0-based)
  getVisibleLines, // Get visible line count
} from "@vimee/plugin-codemirror";

License

MIT