# Completion
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.
## Keyword Go to default configuration
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.
:::tabs
== Prefix
== Full
:::
## Trigger Go to default configuration
Controls when to request completion items from the sources and show the completion menu. The following options are available, excluding their `show_on` prefix:
:::tabs
== Keyword
Shows after typing a keyword, typically an alphanumeric character, `-` or `_`
```lua
completion.trigger.show_on_keyword = true
```
== Trigger Character
Shows after typing a trigger character, defined by the sources. For example for Lua or Rust, the LSP will define `.` as a trigger character.
```lua
completion.trigger.show_on_trigger_character = true
```
== Insert on Trigger Character
Shows after entering insert mode on top of a trigger character.
```lua
completion.trigger.show_on_insert_on_trigger_character = true
```
== Accept on Trigger Character
Shows after accepting a completion item, where the cursor ends up on top of a trigger character.
```lua
completion.trigger.show_on_accept_on_trigger_character = true
```
TODO: Find a case where this actually fires : )
:::
## List Go to default configuration
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.
:::tabs
== Preselect, Auto Insert (default)
```lua
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 ``) will close the menu and undo the preview.
== Preselect
```lua
completion.list.selection = { preselect = true, auto_insert = false }
```
Selects the first item automatically
== Manual
```lua
completion.list.selection = { preselect = false, auto_insert = false }
```
No item will be selected by default. You may use the `select_and_accept` keymap command to select the first item and accept it when there's no selection. The `accept` keymap command, on the other hand, will only trigger if an item is selected.
== Manual, Auto Insert
```lua
completion.list.selection = { preselect = false, auto_insert = true }
```
Selecting an item will insert a "preview" of the item automatically. You may use the `select_and_accept` keymap command to select the first item and accept it when there's no selection. The `accept` keymap command will only trigger if an item is selected. The `cancel` keymap (default ``) will close the menu and undo the preview.
:::
To control the selection behavior per mode, pass a function to `selection.preselect/auto_insert`:
```lua
completion.list.selection = {
preselect = true,
auto_insert = true,
-- or a function
preselect = function(ctx)
return ctx.mode ~= 'cmdline' and not require('blink.cmp').snippet_active({ direction = 1 })
end,
-- auto_insert = function(ctx) return ctx.mode ~= 'cmdline' end,
}
```
## Accept Go to default configuration
Manages the behavior when accepting an item in the completion menu.
### Auto Brackets
> [!NOTE]
> 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!
## Menu Go to default configuration
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.
### Menu Draw Go to default configuration
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 (contributions welcome!, [for example](https://www.reddit.com/r/neovim/comments/1ca4gm2/colorful_cmp_menu_powered_by_treesitter/)). 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:
```lua
completion.menu.draw.columns = { { "label", "label_description", gap = 1 }, { "kind_icon", "kind" } },
```
### Treesitter
You may use treesitter to highlight the label text for the given list of sources. This feature is experimental, contributions welcome!
```lua
completion.menu.draw.treesitter = { 'lsp' }
```
## Documentation Go to default configuration
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.
```lua
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`.
## Ghost Text Go to default configuration
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.
```lua
completion.ghost_text.enabled = true
```
