Coc.nvim

Coc.nvim is a comprehensive Language Server Protocol (LSP) based intellisense engine that brings VSCode-like development experience to Neovim and Vim8. It provides a rich extension ecosystem with support for code completion, diagnostics, code actions, document highlights, formatting, snippets, and workspace management.

Package Information

• Package Name: coc.nvim
• Package Type: npm
• Language: JavaScript (VimScript API with Node.js backend)
• Installation: Plug 'neoclide/coc.nvim', {'branch': 'release'} (vim-plug)
• Requirements: Neovim >= 0.4.0 or Vim >= 8.1.1719, Node.js >= 12.12.0

Quick Start

" Install coc.nvim with vim-plug
Plug 'neoclide/coc.nvim', {'branch': 'release'}

" Install extensions
let g:coc_global_extensions = ['coc-json', 'coc-tsserver', 'coc-python']

" Configure key mappings
nmap <silent> gd <Plug>(coc-definition)
nmap <silent> gy <Plug>(coc-type-definition)
nmap <silent> gi <Plug>(coc-implementation)
nmap <silent> gr <Plug>(coc-references)

" Completion with Tab
inoremap <silent><expr> <TAB>
      \ coc#pum#visible() ? coc#pum#next(1) :
      \ CheckBackspace() ? "\<Tab>" :
      \ coc#refresh()

function! CheckBackspace() abort
  let col = col('.') - 1
  return !col || getline('.')[col - 1]  =~# '\s'
endfunction

Task-to-API Quick Reference

This section helps you quickly find the right API for common tasks:

Code Navigation Tasks

• Jump to definition → <Plug>(coc-definition) or CocAction('jumpDefinition')
• Find references → <Plug>(coc-references) or CocAction('references')
• Go to type definition → <Plug>(coc-type-definition)
• View call hierarchy → CocAction('showIncomingCalls') / CocAction('showOutgoingCalls')
• Browse workspace symbols → :CocList symbols or CocAction('workspaceSymbols')

Code Intelligence Tasks

• Trigger completion → coc#refresh() or coc#start()
• Show hover info → CocAction('doHover') or CocHasProvider('hover')
• View diagnostics → :CocDiagnostics or CocAction('diagnosticList')
• Apply code action → <Plug>(coc-codeaction) or CocAction('codeAction')
• Rename symbol → <Plug>(coc-rename) or CocAction('rename')
• Format code → <Plug>(coc-format) or CocAction('format')

Extension Management Tasks

• Install extension → :CocInstall <extension>
• List extensions → :CocList extensions
• Update extensions → :CocUpdate
• Check extension status → CocAction('extensionStats')

Configuration Tasks

• Edit settings → :CocConfig
• Set config value → coc#config('key', value)
• Get config value → coc#util#get_config('key')

UI Tasks

• Open float window → coc#float#create_float_win()
• Scroll float → coc#float#scroll(1) (down) or coc#float#scroll(0) (up)
• Close floats → coc#float#close_all()
• Show in location list → :CocList location

APIs by Complexity Level

[Basic] Essential APIs for Getting Started

These APIs cover 80% of common use cases and are safe to use for beginners:

Code Navigation

<Plug>(coc-definition)      " Jump to definition
<Plug>(coc-references)      " Find references
<Plug>(coc-implementation)  " Go to implementation

Code Completion

coc#refresh()              " Trigger completion
coc#pum#visible()          " Check if popup visible
coc#pum#confirm()          " Accept completion
coc#_select_confirm()      " Select first and confirm

Diagnostics

:CocDiagnostics                        " Show all diagnostics
<Plug>(coc-diagnostic-next)            " Next diagnostic
<Plug>(coc-diagnostic-prev)            " Previous diagnostic
CocAction('diagnosticInfo')            " Show diagnostic at cursor

Code Actions

<Plug>(coc-codeaction)                 " Show code actions
<Plug>(coc-fix-current)                " Apply quickfix
<Plug>(coc-rename)                     " Rename symbol
CocAction('format')                    " Format buffer

Configuration

:CocConfig                             " Edit settings
:CocInstall <extension>                " Install extension
let g:coc_global_extensions = []       " Auto-install list

[Intermediate] Advanced Feature Usage

These APIs provide more control and are useful once you're comfortable with the basics:

Advanced Navigation

CocAction('jumpDefinition', 'split')   " Jump in split
CocAction('definitions')               " Get definition locations
CocAction('typeDefinitions')           " Get type locations
CocAction('showIncomingCalls')         " View call hierarchy

Smart Completion

coc#start({'source': 'file'})          " Trigger specific source
coc#expandableOrJumpable()             " Check snippet state
coc#pum#select(index, insert, confirm) " Select specific item
CocAction('sourceStat')                " Get source statistics

Diagnostic Management

CocAction('diagnosticList')            " Get all diagnostics
CocAction('diagnosticToggle')          " Toggle diagnostics
CocAction('diagnosticNext', 'error')   " Jump to next error only
CocAction('diagnosticRefresh')         " Force refresh

Code Intelligence

CocAction('codeActions', 'cursor')     " Get available actions
CocAction('quickfixes', 'line')        " Get quickfixes
CocAction('organizeImport')            " Organize imports
CocAction('formatSelected', mode)      " Format selection

Float Windows

coc#float#has_scroll()                 " Check if scrollable
coc#float#scroll(forward, amount)      " Scroll with control
coc#float#jump()                       " Jump to float
coc#float#get_float_win_list()         " Get float windows

[Advanced] Low-Level APIs and Integration

These APIs are for advanced users building custom integrations or workflows:

RPC Communication

CocRequest(id, method, params)         " Sync LSP request
CocRequestAsync(id, method, params, cb) " Async LSP request
CocNotify(id, method, params)          " LSP notification
CocLocations(id, method, ...)          " Query locations

Custom Float Windows

coc#float#create_float_win(winid, bufnr, config)  " Create custom float
coc#float#create_buf(bufnr, lines, mode)          " Create float buffer
coc#float#change_height(winid, delta)             " Resize float

Advanced Utilities

coc#rpc#request(method, args)          " RPC to coc service
coc#api#call(method, args)             " API with error handling
coc#client#create(name, command)       " Create LSP client
coc#util#jump(cmd, filepath, line, col) " Custom jump

Window and Cursor Management

coc#cursor#position()                  " Get LSP position
coc#cursor#move_to(line, character)    " Move to position
coc#window#visible_range(bufnr)        " Get visible range
coc#window#set_var(winid, name, value) " Set window variable

Extension Development

coc#add_command(id, cmd, title)        " Register command
coc#add_extension(...names)            " Add to auto-install
CocAction('activeExtension', name)     " Activate extension
CocAction('reloadExtension', name)     " Reload extension

Common Type Definitions

Many coc.nvim APIs use LSP (Language Server Protocol) data structures:

Position

" LSP Position object (0-indexed)
{
  'line': 5,        " Line number (0-indexed)
  'character': 10   " Character offset (0-indexed, UTF-16 code units)
}

Range

" LSP Range object
{
  'start': {'line': 5, 'character': 0},
  'end': {'line': 5, 'character': 10}
}

Location

" LSP Location object
{
  'uri': 'file:///path/to/file.js',
  'range': {
    'start': {'line': 5, 'character': 0},
    'end': {'line': 5, 'character': 10}
  }
}

Diagnostic

" Diagnostic object
{
  'range': {'start': {...}, 'end': {...}},
  'severity': 1,     " 1=Error, 2=Warning, 3=Information, 4=Hint
  'message': 'Error message',
  'source': 'typescript',
  'code': 'TS2304'
}

Note: Vim uses 1-indexed line/column positions, while LSP uses 0-indexed positions. Coc.nvim handles conversions automatically in most APIs.

Architecture Overview

Coc.nvim uses a client-server architecture:

• VimScript Layer: Handles UI, user input, and Vim integration
• Node.js Service: Separate process managing LSP communication and extensions
• RPC Communication: msgpack-rpc protocol bridges VimScript and Node.js
• Extension System: VSCode-compatible extensions from ~/.config/coc/extensions
• Configuration: JSON-based settings in coc-settings.json with schema validation

Key components:

• Completion engine with custom popup menu
• Diagnostic system with signs, virtual text, and highlights
• Floating window/popup support for hover and signatures
• List interface for fuzzy searching (files, diagnostics, symbols)
• Tree view for outline and call hierarchy
• Multi-cursor support for refactoring
• Snippet engine (VSCode and UltiSnips formats)

Documentation Structure

Core APIs

• Configuration - Settings and config management [Basic]
• Service Management - Start, stop, control service [Basic]
• Extensions - Install and manage extensions [Basic]

Navigation APIs

• Code Navigation - Jump to definitions, references [Basic]
• Symbols & Outline - Document and workspace symbols [Intermediate]
• Call Hierarchy - View function call trees [Intermediate]
• Workspace - Workspace-wide operations [Intermediate]

Intelligence APIs

• Completion - Code completion and popup menu [Basic]
• Diagnostics - Errors, warnings, hints [Basic]
• Code Actions - Refactoring and quick fixes [Basic]
• Formatting - Document and range formatting [Basic]
• Hover & Signatures - Documentation display [Intermediate]

UI APIs

• Float Windows - Floating windows and popups [Intermediate]
• List Interface - Fuzzy finder interface [Intermediate]
• Highlights & Colors - Document highlighting [Intermediate]
• UI Functions - Terminal, messages, signs [Advanced]
• Window Management - Window utilities [Advanced]

Advanced APIs

• RPC & LSP - Direct LSP communication [Advanced]
• Cursor Navigation - Cursor position APIs [Advanced]
• Multi-Cursor - Multiple cursor editing [Intermediate]
• Custom Commands - Register custom commands [Advanced]
• Snippets - Snippet expansion [Intermediate]

Reference

• Variables - Configuration and state variables
• Highlight Groups - All highlight groups
• Autocmd Events - Integration events
• Search - Workspace search

Getting Help

• Check API complexity: Look for [Basic]/[Intermediate]/[Advanced] tags
• Start with "Common Tasks": Most docs begin with task-oriented examples
• Use "See Also" links: Navigate between related topics
• Review "Troubleshooting": Check common issues and solutions
• Consult decision trees: Choose between similar APIs

Performance Tips

• Disable features for large files using buffer variables
• Use async variants (CocActionAsync, CocRequestAsync) for non-blocking operations
• Limit diagnostic refresh in insert mode
• Configure completion timeout and max items
• Disable unused completion sources

Next Steps

1. Beginners: Start with Configuration and Code Navigation
2. Coming from VSCode: Review Code Actions and Completion
3. Advanced users: Explore RPC & LSP for custom integrations
4. Extension developers: Check Custom Commands and extension APIs

For complete documentation, navigate to topic-specific files using the links above.