Lists
Use CocList commands, options, mappings, built-in sources, and the custom List API.
Lists
CocList provides interactive lists for locations, diagnostics, symbols, extensions, commands, services, notifications, and extension-provided sources.
Open and resume lists
| Command | Purpose |
|---|---|
:CocList [options] [source] [args] | Open a list. With no source, opens the lists source. |
:CocListResume [name] | Restore the previous list, including input and cursor position. |
:CocListCancel | Close the active list even when it is not the current window. |
:CocPrev [name] / :CocNext [name] | Run the default action for the previous or next item. |
:CocFirst [name] / :CocLast [name] | Run the default action for the first or last item. |
Arguments after the source are passed to that source. Press ? in normal mode to see its supported arguments.
Command options
| Option | Effect |
|---|---|
--top / --tab | Open at the top or in a new tab page. |
--normal | Start in normal mode. |
--no-sort | Keep source order instead of fuzzy/MRU sorting. |
--input=TEXT | Set the initial input. |
--height=NUMBER | Override list height. |
--strict, -S | Use strict matching. |
--regex, -R | Use regular-expression matching. |
--ignore-case | Ignore case for strict or regex matching. |
--number-select, -N | Type a number to invoke the corresponding item. |
--interactive, -I | Reload items on input changes when the source supports it. |
--auto-preview, -A | Preview the current item immediately. |
--no-quit | Keep the list open after an action. |
--first | Invoke the first item after loading. |
--reverse | Render the first item at the bottom. |
Interactive sources perform their own filtering and sorting, so --strict, --regex, --ignore-case, and --no-sort have no effect. The built-in symbols source is interactive-only.
Configure a source
Use list.source.<name> settings to define a source’s default action, options, and arguments:
| 1 | { |
| 2 | "list.source.symbols.defaultAction": "tabe", |
| 3 | "list.source.symbols.defaultOptions": ["--interactive", "--number-select"], |
| 4 | "list.source.grep.defaultArgs": ["-regex"] |
| 5 | } |
Default options are used only when the command supplies no options; default arguments are used only when it supplies no arguments. Search list. in the Settings Generator for layout, preview, mappings, signs, matching, and status-line settings.
Default mappings
| Mode | Common mappings |
|---|---|
| Insert | <CR> default action, <C-c> stop, <C-l> reload, <C-o> normal mode, <C-n>/<C-p> input history, <C-s> matcher, <Tab> actions. |
| Normal | <CR> default action, <C-a> select all, <C-o> original window, <Space> selection, p preview, ? help, t/d/s/r tabe/drop/split/refactor. |
Customize list.insertMappings and list.normalMappings with expressions such as do:previewtoggle, action:vsplit, prompt:next, feedkeys:..., normal:..., command:..., call:..., and expr:.... Prefer <C-...> or <A-...> keys in insert mode; <Esc> cannot be reassigned.
Built-in list sources
| Source | Default action and notable actions |
|---|---|
location | open; preview, tabe, drop, vsplit, split, quickfix, refactor. |
diagnostics | Location actions; supports buffer, workspace-folder, and severity filters. |
outline | Location actions; document symbols from LSP or ctags. |
symbols | Location actions; interactive workspace-symbol search. |
links | Open or jump to a document link. |
extensions | Toggle, configure, open, disable, enable, lock, help, reload, or uninstall. |
folders | Edit, delete, or create a file in a workspace folder. |
notifications | Clear notification history. |
services | Toggle a registered language-client service. |
commands | Run or append a registered command. |
sources | Toggle, refresh, or open a completion source. |
lists | Open another registered List. |
Extensions can register more sources dynamically. For example, coc-lists adds files, grep, MRU, buffers, quickfix, location list, tags, history, and other Vim-oriented sources.
Custom List sources
Extension authors register an IList with listManager.registerList(). A list supplies name, defaultAction, actions, and loadItems(context, token). It can optionally support interactive loading, custom options, item resolution, highlights, and disposal.
A ListItem can provide a label, filter/sort text, location, data, ANSI highlights, and preselection. For large or streaming results, return a ListTask that emits data, end, and error events and implements dispose().
See the TypeScript API for IList, ListItem, ListTask, ListContext, and listManager.registerList().
Source of truth: :h coc-list.