Based on repository activity, growth velocity and community engagement.
32
Growth4/30
Activity6/25
Popularity11/25
Trust12/20
419
Stars
High
Sentiment
Is this actually an AI agent?
419
README.md
multiple-cursors.nvim
A multi-cursor plugin for Neovim that works in normal, insert/replace, or visual modes, and with almost every command.
Multiple cursors is a way of making multiple similar edits that can be easier, faster, or more flexible than other available methods.
Cursors can be added with an up or down movement, a mouse click, or by searching for a pattern.
This plugin also has the ability to do "split pasting": When pasting text, if the number of lines of text matches the number of cursors, each line will be inserted at each cursor.
Basic usage
For lazy.nvim, add a section to the plugins table, e.g.:
{
"brenton-leighton/multiple-cursors.nvim",
version = "*", -- Use the latest tagged version
opts = {}, -- This causes the plugin setup function to be called
keys = {
{"<C-j>", "<Cmd>MultipleCursorsAddDown<CR>", mode = {"n", "x"}, desc = "Add cursor and move down"},
{"<C-k>", "<Cmd>MultipleCursorsAddUp<CR>", mode = {"n", "x"}, desc = "Add cursor and move up"},
{"<C-Up>", "<Cmd>MultipleCursorsAddUp<CR>", mode = {"n", "i", "x"}, desc = "Add cursor and move up"},
{"<C-Down>", "<Cmd>MultipleCursorsAddDown<CR>", mode = {"n", "i", "x"}, desc = "Add cursor and move down"},
{"<C-LeftMouse>", "<Cmd>MultipleCursorsMouseAddDelete<CR>", mode = {"n", "i"}, desc = "Add or remove cursor on mouse click"},
{"<C-Return>", "<Cmd>MultipleCursorsAddDelete<CR>", mode = {"n"}, desc = "Add a locked cursor or remove an existing cursor"},
{"<Leader>m", "<Cmd>MultipleCursorsAddVisualArea<CR>", mode = {"x"}, desc = "Add cursors to the lines of the visual area"},
{"<Leader>a", "<Cmd>MultipleCursorsAddMatches<CR>", mode = {"n", "x"}, desc = "Add cursors to cword"},
{"<Leader>A", "<Cmd>MultipleCursorsAddMatchesV<CR>", mode = {"n", "x"}, desc = "Add cursors to cword in previous area"},
{"<Leader>d", "<Cmd>MultipleCursorsAddJumpNextMatch<CR>", mode = {"n", "x"}, desc = "Add cursor and jump to next cword"},
{"<Leader>D", "<Cmd>MultipleCursorsJumpNextMatch<CR>", mode = {"n", "x"}, desc = "Jump to next cword"},
{"<Leader>l", "<Cmd>MultipleCursorsLock<CR>", mode = {"n", "x"}, desc = "Lock virtual cursors"},
},
},
Ctrl + j or Ctrl + Down will add a new virtual cursor and move the real cursor down, and Ctrl + k or Ctrl + Up will do the same in the upwards direction.
Ctrl + Left Click will add a new virtual cursor, or remove an existing virtual cursor.
See Creating cursors for more detailed descriptions of the other commands for creating cursors.
After cursors have been added, Neovim can be used mostly as normal.
See Supported commands for more information.
This plugin works by overriding key mappings while multiple cursors are in use.
Any user defined key mappings will need to be added to the custom_key_maps table to be used with multiple cursors.
See the Plugin compatibility section for examples of how to work with specific plugins.
Creating cursors
The plugin creates a number of user commands for creating cursors:
| Command | Description |
| --- | --- |
| MultipleCursorsAddDown | Add a new virtual cursor, then move the real cursor down. </br> If cursors have previously been added in the up direction, this function will instead move the real cursor down and remove any virtual cursor on the same line. See remove_in_opposite_direction for more information. </br> In normal or visual modes multiple new virtual cursors can be added with a count. |
| MultipleCursorsAddUp | Add a new virtual cursor, then move the real cursor up. </br> If cursors have previously been added in the down direction, this function will instead move the real cursor up and remove any virtual cursor on the same line. See remove_in_opposite_direction for more information. </br> In normal or visual modes multiple new virtual cursors can be added with a count. |
| MultipleCursorsAddDelete | Add a new virtual cursor at the real cursor position, or remove an existing cursor. </br> If adding, this will also lock the virtual cursors if they aren't already locked. |
| MultipleCursorsMouseAddDelete | Add a new virtual cursor to the mouse click position, or remove an existing cursor |
| MultipleCursorsAddVisualArea | Add virtual cursors to each line of the visual area |
| MultipleCursorsAddMatches | Search for the word under the cursor (in normal mode) or the visual area (in visual mode) and add a new cursor to each match. By default cursors are only added to matches in the visible buffer. |
| MultipleCursorsAddMatchesV | As above, but limit matches to the previous visual area |
| MultipleCursorsAddJumpNextMatch | Add a virtual cursor to the word under the cursor (in normal mode) or the visual area (in visual mode), then move the real cursor to the next match |
| MultipleCursorsJumpNextMatch | Move the real cursor to the next match of the word under the cursor (in normal mode) or the visual area (in visual mode) |
| MultipleCursorsAddJumpPrevMatch | Add a virtual cursor to the word under the cursor (in normal mode) or the visual area (in visual mode), then move the real cursor to the previous match |
| MultipleCursorsJumpPrevMatch | Move the real cursor to the previous match of the word under the cursor (in normal mode) or the visual area (in visual mode) |
Other functions
Locking cursors
The MultipleCursorsLock user command will toggle locking the virtual cursors.
It can be used by adding it to the keys table, e.g.:
The align function will insert spaces before each cursor in order to align the cursors vertically with the rightmost cursor.
It can be used by adding it to the custom_key_maps table, e.g.:
The following commands are supported while using multiple cursors:
| Mode | Description | Commands | Notes |
| --- | --- | --- | --- |
| All | Left/right motion | <Left><Right><Home><End> | |
| Normal/visual | Left/right motion | h<BS>l<Space>0^$\| | |
| Normal/visual | Left/right motion | fFtT | These don't indicate that they're waiting for a character |
| All | Up/down motion | <Up><Down> | |
| Normal/visual | Up/down motion | jk-+<CR>kEnter_ | |
| All | Text object motion | <C-Left><C-Right> | |
| Normal/visual | Text object motion | wWeEbBgegE | |
| Normal/visual | Percent symbol | % | Count is ignored, i.e. jump to match of item under cursor only |
| Normal | Go to | ggG | Moves the first cursor in the buffer to line count (or line 1 for gg with no count) and subsequent cursors to subsequent lines. </br> If cursors will be positioned past the end of the buffer (like for the G command with no count), cursors are placed in order on the last lines of the buffer. |
| Normal | Delete | x<Del>XdddD | d doesn't indicate that it's waiting for a motion. <br/> See Registers for information on how registers work. |
| Normal | Change | cccCs | These commands are implemented as a delete then switch to insert mode. <br/> c doesn't indicate that it's waiting for a motion, and using a w or W motion may not behave exactly correctly. <br/> The cc command won't auto indent. <br/> See Registers for information on how registers work. |
| Normal | Replace | r | |
| Normal | Yank | yyy | y doesn't indicate that it's waiting for a motion. <br/> See Registers for information on how registers work. |
| Normal | Put | pP | See Registers for information on how registers work |
| Normal | Indentation | >><< | |
| Normal | Join | JgJ | |
| Normal | Repeat | . | |
| Normal | Change to insert/replace mode | aAiIoOR | Count is ignored |
| Normal | Change to visual mode | v | |
| Insert/replace | Character insertion | | |
| Insert/replace | Non-printing characters | <BS><Del><CR><Tab> | These commands are implemented manually, and may not behave correctly <br/> In replace mode <BS> will only move any virtual cursors back, and not undo edits |
| Insert/replace | Delete word before | <C-w> | |
| Insert/replace | Indentation | <C-t><C-d> | |
| Insert/replace | Completion | <C-n><C-p> <br/> <C-x> ... | Using backspace while completing a word will accept the word |
| Insert | Change to replace mode | <Insert> | |
| Visual | Swap cursor to other end of visual area | o | |
| Visual | Modify visual area | awiwaWiWabibaBiBa>i>atita'i'a"i"a`i` | |
| Visual | Join lines | JgJ | |
| Visual | Indentation | <> | |
| Visual | Change case | ~uUg~gugU | |
| Visual | Yank/delete | yd<Del> | |
| Visual | Change | c | This command is implemented as a delete then switch to insert mode |
| All | Paste | | Split pasting is enabled by default |
| Insert/replace/visual | Exit to normal mode | <Esc> | |
| Normal | Exit multiple cursors | <Esc> | Clears all virtual cursors. <br/> Virtual cursor registers are merged into the real registers. |
| Normal | Undo | u | Also exits multiple cursors, because cursor positions can't be restored by undo |
Registers
The delete, yank, and put commands support named registers in addition to the unnamed register, and each virtual cursor has its own registers.
If the put command is used and a virtual cursor doesn't have a register available, the register for the real cursor will be used.
This means that if you use delete/yank before creating multiple cursors, add cursors, and then use the put command, the same text will be put to each cursor.
When exiting multiple cursors, any virtual cursor register will be merged into the matching real register.
Notable unsupported functionality
Scrolling
Jumping to marks (` or ' commands)
Commenting in Neovim 0.10+
Neovim 0.10+ includes a plugin for commenting (inherited from Vim) which is mapped to gc and gcc.
Because these commands need to be called with remap = true it doesn't seem to be possible to map them for use with multiple cursors.
You can however use them from a different key combination using custom_key_maps, e.g.
Options can be configured by providing an options table to the setup function, e.g. to define the pre_hook and post_hook functions:
{
"brenton-leighton/multiple-cursors.nvim",
version = "*",
opts = {
pre_hook = function()
vim.cmd("set nocul")
vim.cmd("NoMatchParen")
end,
post_hook = function()
vim.cmd("set cul")
vim.cmd("DoMatchParen")
end,
},
keys = {
{"<C-j>", "<Cmd>MultipleCursorsAddDown<CR>", mode = {"n", "x"}, desc = "Add a cursor then move down"},
{"<C-Down>", "<Cmd>MultipleCursorsAddDown<CR>", mode = {"n", "i", "x"}, desc = "Add a cursor then move down"},
{"<C-k>", "<Cmd>MultipleCursorsAddUp<CR>", mode = {"n", "x"}, desc = "Add a cursor then move up"},
{"<C-Up>", "<Cmd>MultipleCursorsAddUp<CR>", mode = {"n", "i", "x"}, desc = "Add a cursor then move up"},
{"<C-LeftMouse>", "<Cmd>MultipleCursorsMouseAddDelete<CR>", mode = {"n", "i"}, desc = "Add or remove a cursor"},
{"<Leader>a", "<Cmd>MultipleCursorsAddMatches<CR>", mode = {"n", "x"}, desc = "Add cursors to the word under the cursor"},
},
},
remove_in_opposite_direction
Default value: true
With this enabled, when MultipleCursorsAddUp or MultipleCursorsAddDown are used to add cursors, the command for adding in the opposite direction will instead remove a virtual cursor. The initial direction is stored until multiple cursors is exited.
Disabling this will mean that cursors are always added when using the MultipleCursorsAddUp and MultipleCursorsAddDown commands (unless there is an existing cursor in the position).
enable_split_paste
Default value: true
This option allows for disabling the "split pasting" function, where if the number of lines in the paste text matches the number of cursors, each line of the text will be inserted at each cursor.
match_visible_only
Default value: true
When adding cursors to the word under the cursor (i.e. using the MultipleCursorsAddMatches command), if match_visible_only = true then new cursors will only be added to matches that are in the visible buffer.
pre_hook and post_hook
Default values: nil
These options are to provide functions that are called when the first virtual cursor is added (pre_hook) and when the last virtual cursor is removed (post_hook).
This option allows for mapping keys to custom functions for use with multiple cursors.
This can also be used to disable a default key mapping.
Each element in the custom_key_maps table must have three or four elements:
Mode (string|table): Mode short-name string ("n", "i" or "x"), or a table of mode short-name strings (for visual mode it's currently only possible to move the cursor)
Mapping lhs (string|table): Left-hand side of a mapping string, e.g. ">>", "<Tab>", or "<C-/>", or a table of lhs strings
Function: A Lua function that will be called at each cursor, which receives register (note: working with virtual cursor registers is not currently implemented), count, and optionally more, as arguments. Setting this to nil will disable a default key mapping.
Option: A optional string containing "m", "c", "mc", or "nowrap". "m", "c", and "mc" enable getting input from the user, which is then forwarded to the function:
"m" indicates that a motion command is requested (i.e. operator pending mode). The motion command can can include a count in addition to the count variable.
"c" indicates that a printable character is requested (e.g. for character search)
"mc" indicates that a motion command and a printable character is requested (e.g. for a surround action)
If valid input isn't given by the user the function will not be called
There will be no indication that Neovim is waiting for a motion command or character
The "nowrap" option is for using an internal function, e.g. for alternative keyboard layouts. Custom key map functions are typically executed for every virtual cursor, but internal functions already do this, so the "nowrap" option causes the given function to be called only once.
The following example shows how to use various options for user input:
The "nowrap" option for a custom key map allows for using internal functions.
This can be used to remap keys for alternative keyboard layouts, e.g. for the Colemak layout (with the l key for changing to insert mode):
opts = {
custom_key_maps = {
-- Remap j, k, and l to n, e, and i
{{"n", "x"}, "n", function() require("multiple-cursors.normal_mode.motion").j() end, "nowrap"},
{{"n", "x"}, "e", function() require("multiple-cursors.normal_mode.motion").k() end, "nowrap"},
{{"n", "x"}, "i", function() require("multiple-cursors.normal_mode.motion").l() end, "nowrap"},
-- Remap i and I to l and L
{{"n", "x"}, "l", function() require("multiple-cursors.normal_mode_mode_change.i() end, "nowrap"},
{{"n", "x"}, "L", function() require("multiple-cursors.normal_mode_mode_change.I() end, "nowrap"},
-- Disable j and k
{{"n", "x"}, "j", nil },
{{"n", "x"}, "k", nil },
}
}
Plugin functions can be used from custom key maps.
Plugins should work even if they are lazy loaded after adding multiple cursors, because this plugin will reapply custom key mappings on the LazyLoad event to handle the mappings being overridden.
If it's necessary to load a plugin before using multiple cursors, you can do so in the pre_hook function, e.g.
Some plugins may need to be disabled while using multiple cursors.
Use the pre_hook function to disable the plugin, then the post_hook function to re-enable it.
Adds characters to surround text.
The issue with both of these plugins is that they don't have functions that can be given the motion and character as arguments.
One workaround would be to use a different key sequence to execute the command while using multiple cursors, e.g. for mini.surround sa command:
Improves w, e, and b motions.
For normal mode count must be set before nvim-spider's motion function is called:
custom_key_maps = {
-- w
{{"n", "x"}, "w", function(_, count)
if count ~=0 and vim.api.nvim_get_mode().mode == "n" then
vim.cmd("normal! " .. count)
end
require('spider').motion('w')
end},
-- e
{{"n", "x"}, "e", function(_, count)
if count ~=0 and vim.api.nvim_get_mode().mode == "n" then
vim.cmd("normal! " .. count)
end
require('spider').motion('e')
end},
-- b
{{"n", "x"}, "b", function(_, count)
if count ~=0 and vim.api.nvim_get_mode().mode == "n" then
vim.cmd("normal! " .. count)
end
require('spider').motion('b')
end},
},
Shows a pop up of possible key bindings for a given command.
There's an issue with the normal v command that, if a movement command is used before timeoutlen, the position of the start of the visual area will be incorrect.
The best solution seems to be disabling the command, e.g. by using a plugin spec for which-key like this:
where lnum is the line number of the new cursor, col is the column, and curswant is the desired column. Typically curswant will be the value same as col, although it can be larger if the cursor position is limited by the line length. If the cursor is to be positioned at the end of a line, curswant would be equal to vim.v.maxcol.
Notes and known issues
In insert/replace mode, Backspace, Delete, Enter, or Tab may behave incorrectly, in particular with less common indentation options. Please use the Issues page to report issues.
When virtual cursors are locked, switching to or from visual mode won't update the virtual cursors and should be avoided
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.