multicursor.nvim Setup and Use in Neovim

Why multicursor.nvim Adds Cursors to Neovim

multicursor.nvim addresses edits that would otherwise require visiting and changing each target location separately. It can place cursors above or below the current position, find matching words or selections, cover search results and diagnostics, and derive cursors from paragraphs or visual ranges. According to the README, users then operate on those cursors as they would with a single Vim cursor. The project is therefore aimed at Neovim users who want temporary multi-location editing without leaving the editor or adopting a separate editing interface.

The plugin covers Normal, insert, and replace modes. It also supports visual and select modes with character, line, and block selections. The feature list further includes undo and redo, `Virtualedit`, autocompletion, snippet expansion through `vim.snippet.expand`, and cursor-specific registers for searching and yanking. These details matter because multiple-cursor editing is not limited to duplicating a cursor and pressing a key. The plugin tries to preserve familiar editor operations around each active cursor.

multicursor.nvim is written in Lua. Its repository contains implementation files under `lua/`, documentation under `doc/`, and a configuration-oriented README. The project also provides built-in help through `:h multicursor`. It does not prescribe one complete keymap. Instead, the documented Lua functions can be attached to different keys with `vim.keymap.set`, which gives users control over conflicts but also requires them to construct the editing workflow.

How Cursor Matching and Selection Works

Cursor selection begins with directional operations and matching operations. In the lazy.nvim example, `mc.lineAddCursor(-1)` and `mc.lineAddCursor(1)` add cursors above and below the main cursor. Their skip counterparts, `mc.lineSkipCursor(-1)` and `mc.lineSkipCursor(1)`, pass lines while deciding where to place the next cursor. This distinction lets a user either include every intervening line or skip selected lines.

Word and selection matching follows the same pattern. `mc.matchAddCursor(1)` moves through matching words or selections forward and adds a cursor, while `mc.matchAddCursor(-1)` works backward. `mc.matchSkipCursor(1)` and `mc.matchSkipCursor(-1)` move past matches instead of adding them. For document-wide changes, `mc.matchAllAddCursors` creates cursors for every match of the current word or selection in the buffer.

Search and diagnostics are also cursor sources. Functions named `mc.searchAddCursor`, `mc.searchSkipCursor`, and `mc.searchAllAddCursors` respectively add search results, pass search results, or select every result in the buffer. Diagnostic actions use `mc.diagnosticAddCursor`, `mc.diagnosticSkipCursor`, and `mc.diagnosticMatchCursors`. The diagnostic matcher accepts options such as a severity filter, with the README referring users to `:h vim.diagnostic.GetOpts`.

Visual ranges have separate mechanisms. `mc.splitCursors` divides visual selections by regex, and `mc.matchCursors` locates regex matches inside those selections. `mc.addCursorOperator` can create a cursor for every line in a paragraph or visual selection when used after `ga`. This design keeps whole-document matching distinct from edits constrained by a visual range.

Installing multicursor.nvim Through lazy.nvim

The README documents installation as part of a lazy.nvim plugin specification rather than as a standalone shell command. The following configuration installs the `1.0` branch, requires `multicursor-nvim`, runs `mc.setup()`, and assigns the example keymaps. Neovim should load the specification during startup if lazy.nvim is already configured as the plugin manager.

{
    "jake-stewart/multicursor.nvim",
    branch = "1.0",
    config = function()
        local mc = require("multicursor-nvim")
        mc.setup()
        mc.addKeymapLayer(function(layerSet)
            layerSet("n", "<esc>", function()
                if not mc.cursorsEnabled() then
                    mc.enableCursors()
                else
                    mc.clearCursors()
                end
            end)
        end)
    end
}

After Neovim loads that specification, open a buffer and map `<leader>n` to `mc.matchAddCursor(1)`. Place the main cursor on a word, press the mapping, and repeat it until several cursors select matching occurrences. Enter Insert mode and make a short change. Use undo to restore the buffer, then press `<esc>` to clear the cursors. This is the first real workflow documented by the available APIs: create cursors from repeated text, edit through them, and collapse the multicursor state.

The README does not document an installation procedure for a plugin manager other than lazy.nvim, so the article does not substitute an invented Git, package, or configuration command. Users without lazy.nvim would need to consult the repository's current Neovim plugin installation instructions, but none are included in the README shown here.

Editing Several Visual and Search Locations

Once cursors exist, the README says to use Vim normally as with a single cursor. That principle covers insert and replace operations, but multicursor.nvim also exposes higher-level actions for repeated transformations. `mc.alignCursors` aligns the columns occupied by the current cursors. `mc.transposeCursors(1)` and `mc.transposeCursors(-1)` rotate the text inside each visual selection in either direction.

Visual insertion has dedicated functions. Mapping `mc.insertVisual` to `I` inserts on each line covered by the visual selections, while mapping `mc.appendVisual` to `A` appends on those lines. The README characterizes these actions as similar to block-selection insertion. Sequence operations treat all cursors as one sequence: `mc.sequenceIncrement` and `mc.sequenceDecrement` increment or decrement numbers across the cursor set rather than treating each number independently.

Search actions can extend the same batch-editing model beyond exact words. `mc.searchAddCursor(1)` and `mc.searchAddCursor(-1)` add the next or previous search result, while `mc.searchSkipCursor(1)` and `mc.searchSkipCursor(-1)` navigate without adding it. `mc.searchAllAddCursors` selects every result in the buffer. This is useful when a search pattern defines the edit set, although the README does not discuss behavior for overlapping matches, changing buffers during a search operation, or large result counts.

The plugin also documents an operator interface. Mapping `mc.operator` to `<leader>m` and entering `miwap` creates cursors for every match of the captured inner word within the paragraph range. The README describes this action as customizable and points to `:h multicursor-operator`. Operators are a more advanced route because their behavior depends on the range and text object supplied after the mapping.

Keymap Layers and Mouse Cursor Control

multicursor.nvim separates normal mappings from mappings intended only for active cursor sets. `mc.addKeymapLayer` registers the latter, allowing keys such as `<left>`, `<right>`, and `<esc>` to handle cursor movement, deletion, and cleanup without permanently replacing their single-cursor behavior. Within that layer, the example binds `mc.prevCursor`, `mc.nextCursor`, and `mc.deleteCursor`, giving the user explicit control over which cursor is primary.

The regular mappings still need to create and disable cursors. The documented example maps `<up>` and `<down>` to `mc.lineAddCursor`, maps `<leader>n` and `<leader>N` to forward and backward matching, and binds `<c-q>` to `mc.toggleCursor`. According to the README, disabled cursors leave only the main cursor moving. Pressing `<c-q>` while they are disabled adds a cursor beneath the main cursor.

Mouse input is also configurable. `mc.handleMouse`, `mc.handleMouseDrag`, and `mc.handleMouseRelease` are mapped to `<c-leftmouse>`, `<c-leftdrag>`, and `<c-leftrelease>` for adding or removing cursors. This gives visual placement of cursor locations, but users who already use modified left-click should inspect these conflicts rather than assuming the bindings are neutral.

Appearance is controlled through named highlight groups. The example connects `MultiCursorVisual` to `Visual`, `MultiCursorSign` to `SignColumn`, and `MultiCursorMatchPreview` to `Search`. Separate disabled groups distinguish inactive cursor state. If a colorscheme changes frequently, a local colorscheme may need to define these groups again.

Limitations of Mode and Plugin Compatibility

multicursor.nvim has a real contextual limitation: its actions depend on mode, selection, cursor state, and the available editor data. Visual functions such as `mc.splitCursors`, `mc.matchCursors`, `mc.insertVisual`, and `mc.appendVisual` expect a visual selection. Normal-mode functions such as `mc.alignCursors` do not represent the same input shape. A global key binding can therefore trigger an inappropriate operation unless it is restricted to the documented modes.

The README says the plugin works with most plugins and remaps, but it does not name tested integrations or provide a compatibility matrix. That wording cannot establish that every completion engine, snippet provider, text object plugin, or remapping layer will behave correctly with every cursor. Autocompletion and `vim.snippet.expand` are listed as supported features, yet no examples show a particular completion engine producing multiple candidates at each cursor. Users with a mandatory completion stack need to verify those interactions directly.

Cursor-specific registers are also listed without a register example or naming scheme in the README. Undo and redo are supported features, but the documentation does not explain how restored cursor sets are merged into an existing multicursor session. The project may handle those cases through its Cursor API, but this README section does not define the full contract.

multicursor.nvim is also the wrong tool for a user who wants a fixed, discoverable command scheme without writing mappings. Its central design is user-owned configuration. The absence of GitHub releases further leaves the README's `1.0` branch as the only version-selection instruction documented here, so branch-level changes deserve attention when updating.

Maintenance and the Cost of Following the 1.0 Branch

The GitHub repository is not archived, and its last push was on 2026-10-16. Those are the available maintenance facts, but they do not establish a release schedule or a promise of compatibility. The repository has no GitHub releases, so there is no numbered release to compare with the `1.0` branch selected by the README. Users should not assume that branch naming supplies the same guarantees as a tagged release.

The project declares the MIT License. That license permits use, modification, distribution, and sublicensing subject to its conditions, including preservation of the applicable copyright and permission notice. Whether a particular installation meets every condition is outside this review. The operational upgrade cost is more relevant to Neovim users: a plugin-manager update may retrieve new code from the configured branch, and changed Lua or documentation files could alter functions or help content.

The built-in `:h multicursor` page is the documented place for fuller command and API information. A user should compare that help with the mappings currently running in Neovim after an update, especially if a configuration depends on `mc.addKeymapLayer`, the `Cursor API`, or an operator. The README does not publish a migration procedure or compatibility policy, so there is no documented rollback command to recommend.

Compared with a plugin that installs one command set, multicursor.nvim transfers more upgrade ownership to the user. Lua mappings may need review when APIs change, although maintenance burden is limited for someone comfortable with Neovim configuration. For users who prefer immutable plugin versions, the lack of GitHub releases and the documented branch dependency are concrete adoption constraints.

Editorial conclusion

Adopt multicursor.nvim if your Neovim editing repeatedly touches many locations in one buffer and you want each multicursor action bound through Lua. Do not adopt it if you require fixed, fully documented commands without configuration, or if your workflow depends on an editor plugin whose multicursor behavior has not been checked. First verify the documented `1.0` branch configuration, then exercise a small match-and-edit operation in Normal, Insert, and Visual modes. The keymap layer, mode-specific actions, and actual plugin compatibility are more immediate adoption checks than the repository having no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. jake-stewart/multicursor.nvim on GitHub
3. License: MIT
4. README