doc/configuration/completion.md
Blink cmp has a lot of configuration options, the following document tries to highlight the ones you'll likely care the most about for each section. For all options, click on the "Go to default configuration" button next to each header.
<!-- panvimdoc-include-comment The online documentation contains images and videos for each section. You may have a better experience viewing the docs on that website: https://cmp.saghen.dev/configuration/completion -->Controls what the plugin considers to be a keyword, used for fuzzy matching and triggering completions. Most notably, the range option controls whether the keyword should match against the text before and after the cursor, or just before the cursor.
Controls when to request completion items from the sources and show the completion menu. The following options are available, excluding their show_on prefix:
Shows after typing a keyword, typically an alphanumeric character, - or _
completion.trigger.show_on_keyword = true
Manages the completion list and its behavior when selecting items. The most commonly changed option is selection.preselect/auto_insert, which controls whether the list will automatically select the first item in the list, and whether a "preview" will be inserted on selection.
::: info
The completion list in cmdline mode does not inherit the following settings from the default mode. To control its behavior, explicitly configure cmdline.completion.list. See cmdline mode for more information.
:::
completion.list.selection = { preselect = true, auto_insert = true }
Selects the first item automatically, and inserts a preview of the item on selection. The cancel keymap (default <C-e>) will close the menu and undo the preview.
You may use the show_and_insert keymap to show the completion menu and select the first item, with auto_insert. The default keymap (<C-space>) uses the show command, which will have the first item selected, but will not auto_insert.
To control the selection behavior dynamically, pass a function to selection.preselect/auto_insert:
completion.list.selection = {
preselect = true,
auto_insert = true,
-- or a function
preselect = function(ctx)
return not require('blink.cmp').snippet_active({ direction = 1 })
end,
auto_insert = function(ctx) return vim.bo.filetype ~= 'markdown' end,
}
Manages the behavior when accepting an item in the completion menu.
::: info Some LSPs may add auto brackets themselves. You may be able to configure this behavior in your LSP client configuration :::
LSPs provide a kind field for completion items, indicating whether the item is a function, method, variable, etc. The plugin will automatically add brackets for functions/methods and place the cursor inside the brackets. For items not marked as such, the plugin will asynchronously resolve the semantic tokens from the LSP and add brackets if marked as a function. A default list of brackets have been included in the default configuration, but you may add more in the configuration (contributions welcome!).
If brackets are showing when you don't expect them, try disabling kind_resolution or semantic_token_resolution for that filetype (echo &filetype). If that fixes the issue, please open a PR setting this as the default!
Manages the appearance of the completion menu. You may prevent the menu from automatically showing by setting completion.menu.auto_show = false and manually showing it with the show keymap command.
blink.cmp uses a grid-based layout to render the completion menu. The components, defined in draw.components[string], define text and highlight functions which are called for each completion item. The highlight function will be called only when the item appears on screen, so expensive operations such as Treesitter highlighting may be performed. The components may define their min and max width, where ellipsis = true (enabled by default), will draw the … character when the text is truncated. Setting width.fill = true will fill the remaining space, effectively making subsequent components right aligned, with respect to their column.
Columns effectively allow you to vertically align a set of components. Each column, defined as an array in draw.columns, will be rendered for all of the completion items, where the longest rendered row will determine the width of the column. You may define gap = number in your column to insert a gap between components.
For a setup similar to nvim-cmp, use the following config:
completion.menu.draw.columns = { { "label", "label_description", gap = 1 }, { "kind_icon", "kind" } },
kind_icon: Shows the icon for the kind of the itemkind: Shows the kind of the item as text (e.g. Function)label: Shows the label of the item as well as the label_detail (e.g. into(as Into) where into is the label and (as Into) is the label detail)
label_detail is missing from your items, ensure you've setup LSP capabilities and that your LSP supports the featurelabel_description: Shows the label description of the item (e.g. date-fns/formatDistance, the module that the item will be auto-imported from)
label_description is missing from your items, ensure you've setup LSP capabilities and that your LSP supports the featuresource_name: Shows the name of the source that provided the item, from the sources.providers.*.name (e.g. LSP)source_id: Shows the id of the source that provided the item, from the sources.providers[id] (e.g. lsp)The cursorline background will be rendered with a priority of 10000 to ensure that highlights with backgrounds (such as those from the default theme) will be overridden by the cursorline. If you'd like to use a background in your highlight, set the priority to 10001 or higher.
completion.menu.draw.components.label.kind_icon.highlight = function(ctx)
return { { group = ctx.kind_hl, priority = 20000 } }
end
Or you may set the cursorline highlight priority to 0
completion.menu.draw.cursorline_priority = 0
You may use treesitter to highlight the label text for the given list of sources. This feature is barebones, as it highlights the item as-is.
completion.menu.draw.treesitter = { 'lsp' }
The wonderful colorful-menu.nvim takes this a step further by including context around the item before highlighting.
By default, the documentation window will only show when triggered by the show_documentation keymap command. However, you may add the following configuration to show the documentation whenever an item is selected.
completion.documentation = {
auto_show = true,
auto_show_delay_ms = 500,
}
If you're noticing high CPU usage or stuttering when opening the documentation, you may try setting completion.documentation.treesitter_highlighting = false. You may completely override the drawing of the window via completion.documentation.draw.
Ghost text shows a preview of the currently selected item as virtual text inline. You may want to try setting completion.menu.auto_show = false and enabling ghost text, or you may use both in parallel.
completion.ghost_text.enabled = true
-- you may want to set the following options
completion.menu.auto_show = false -- only show menu on manual <C-space>
completion.ghost_text.show_with_menu = false -- only show when menu is closed