Custom Completion Sources
Create Vimscript or TypeScript completion sources with current coc.nvim APIs, async callbacks, source options, cancellation, resolution, and disposal.
Custom Completion Sources
Choose a Vim source for a small runtimepath plugin with simple completion items. Choose the Node/TypeScript provider API when you need LSP TextEdit, additional edits, commands, cancellation, resolution, or richer item behavior.
Minimal Vim source
coc.nvim loads autoload/coc/source/{name}.vim from Vim’s runtimepath. The init() and complete(option, callback) functions are required.
| 1 | function! coc#source#email#init() abort |
| 2 | return { |
| 3 | \ 'priority': 9, |
| 4 | \ 'shortcut': 'Email', |
| 5 | \ 'triggerCharacters': ['@'] |
| 6 | \ } |
| 7 | endfunction |
| 8 | |
| 9 | function! coc#source#email#complete(option, callback) abort |
| 10 | call a:callback(['[email protected]', '[email protected]']) |
| 11 | endfunction |
Vim9 script sources are supported on Vim9, not Neovim; their exported function names must start with uppercase letters (Init, Complete).
Source options
init() may return shortcut, priority, filetypes, firstMatch, triggerCharacters, triggerOnly, and isSnippet. All are optional.
Users can override a source with coc.source.<name>.enable, disableSyntaxes, firstMatch, priority, shortcut, and filetypes.
Completion input and items
The completion option includes buffer and cursor state such as bufnr, line, col, input, filetype, filepath, changedtick, triggerCharacter, colnr, and linenr. The callback may run asynchronously and receives a list or v:null; synchronous work blocks Vim.
Only word is required on an item. Vim sources can additionally provide label details, sorting/filter text, snippets, deprecation, and documentation, but they do not support the complete LSP edit/command model.
Optional Vim hooks
coc#source#{name}#get_startcol(option)changes the start column.coc#source#{name}#on_complete(item)applies work after confirmation.coc#source#{name}#on_enter(option)reacts to buffer entry.coc#source#{name}#refresh()refreshes cached source state.
Use :CocOpenLog to inspect errors; completion errors are logged rather than thrown into Vim.
TypeScript provider
An extension can register a CompletionItemProvider with languages.registerCompletionItemProvider(). Dispose the returned registration through ExtensionContext.subscriptions.
| 1 | import { CompletionItemKind, ExtensionContext, languages } from 'coc.nvim' |
| 2 | |
| 3 | export function activate(context: ExtensionContext): void { |
| 4 | context.subscriptions.push( |
| 5 | languages.registerCompletionItemProvider( |
| 6 | 'email', |
| 7 | 'Email', |
| 8 | [{ language: 'markdown' }], |
| 9 | { |
| 10 | provideCompletionItems: (_document, _position, token) => { |
| 11 | if (token.isCancellationRequested) return [] |
| 12 | return [{ |
| 13 | label: '[email protected]', |
| 14 | kind: CompletionItemKind.Value, |
| 15 | insertText: '[email protected]', |
| 16 | }] |
| 17 | }, |
| 18 | }, |
| 19 | ['@'], |
| 20 | 9, |
| 21 | ), |
| 22 | ) |
| 23 | } |
The provider can implement resolveCompletionItem, honor cancellation, return snippets and text edits, and declare trigger or commit characters. See CompletionItemProvider, languages.registerCompletionItemProvider(), and Disposable in the TypeScript API.
Source of truth: doc/coc-api.txt.