Multiple cursors support

With the multiple cursors feature, you can change many places of the current document at one time.

Multiple cursors are actually multiple text ranges.

The ranges are highlighted by the CocCursorRange highlight group (linked to Search by default). To override the highlight, put this:

hi CocCursorRange guibg=#b16286 guifg=#ebdbb2

in your .vimrc

Start a multiple cursors session

The following keymaps start a multicursor session:

• <Plug>(coc-cursors-position) adds the current character range to the cursors.
• <Plug>(coc-cursors-word) adds the current word range to the cursors.
• <Plug>(coc-cursors-range) adds the currently selected visual range to the cursors.
• <Plug>(coc-cursors-operator) uses an operator to add a range to the cursors.

You can cancel the range under the cursor by triggering one of those keymaps.

Example usage:

nmap <silent> <C-c> <Plug>(coc-cursors-position)
nmap <silent> <C-d> <Plug>(coc-cursors-word)
xmap <silent> <C-d> <Plug>(coc-cursors-range)
" use normal command like `<leader>xi(`
nmap <leader>x  <Plug>(coc-cursors-operator)

or use the following to add the current word to the selection and go to the next one:

nmap <silent> <C-d> <Plug>(coc-cursors-word)*
xmap <silent> <C-d> y/\V<C-r>=escape(@",'/\')<CR><CR>gN<Plug>(coc-cursors-range)gn

Or, for more VS Code-like behavior:

nmap <expr> <silent> <C-d> <SID>select_current_word()
function! s:select_current_word()
  if !get(b:, 'coc_cursors_activated', 0)
    return "\<Plug>(coc-cursors-word)"
  endif
  return "*\<Plug>(coc-cursors-word):nohlsearch\<CR>"
endfunc

Or use an internal command API to add ranges, like:

import {commands} from 'coc.nvim'
// hlRanges is a list of LSP Range
await commands.executeCommand('editor.action.addRanges', hlRanges)

Or with vim script:

call CocAction('runCommand', 'editor.action.addRanges', hlRanges)

Rename current variable

One common task is renaming the variable under the cursor.

Use the :CocCommand document.renameCurrentWord command to start a multicursor session with ranges containing the current word.

Note: the word ranges are extracted from the language server when possible. When a language server isn't available, strict matching of words in the current buffer is used.

Make changes for cursors

When a multicursor session is activated, changing one placeholder reflects the change across all cursor ranges.

• You can change the text in any way you want, for example with normal commands or by inserting text.
• You can change text around the cursors with commands like ysiw" (with tpope/vim-surround installed).
• You can undo and redo the changes.
• You can't insert a new line within cursor ranges; it would cancel the cursors session.

Jump between ranges of cursors

• Use "cursors.nextKey" to jump to the next position in a cursor range; defaults to <C-n>.
• Use "cursors.previousKey" to jump to the previous position in a cursor range; defaults to <C-p>.

The key-mappings are created when a cursors session is activated and removed when the session is cancelled.

Cancel cursors session

Use "cursors.cancelKey" to cancel the cursors session; defaults to <Esc>.

The session is also cancelled when a buffer change can't be applied to the ranges.

Use refactor action

Use <Plug>(coc-refactor) to create a refactor window for the current symbol.

Note: it requires the language server's rename feature.

When the window opens, related ranges are added to a new cursors session. You can:

• Change the placeholder to rename.
• Save the buffer to synchronize changes to related buffers.
• Add or remove lines.
• Press <CR> to open the line under the cursor in a right split window.
• Change the content of related buffers; the changes will be synchronized to the refactor buffer.
• Fold the ranges with commands like zi.

Available configurations for refactor:

• refactor.openCommand: command used to open the refactor window; defaults to vsplit.
• refactor.beforeContext: number of leading context lines to print before each match; defaults to 3.
• refactor.afterContext: number of trailing context lines to print after each match; defaults to 3.

Use CocSearch command

To rename a variable across files in the current cwd, use the :CocSearch command, which requires ripgrep.

Each range of lines is added to the refactor window asynchronously, and matched ranges are added to a cursors session for renaming.

Tips:

• Don't change the buffer when search is not finished.
• Use <tab> after typing the :CocSearch command to see the available options.
• Use :CocSearch -w [word] for whole-word matching.