## File: README.md

> [!WARNING]
> V2 is under active development with many breaking changes. Consider staying on stable by using `branch = 'v1'` or `version = "1.*"` in your `lazy.nvim` config. [See the V1 docs](https://cmp.saghen.dev/)
>
> For V2, [blink.lib](https://github.com/saghen/blink.lib) must be installed via your package manager. See the [UPGRADE.md](./UPGRADE.md) for a detailed migration guide.









**blink.cmp** is a completion plugin with support for LSPs, cmdline, signature help, and snippets. It uses an [optional](https://cmp.saghen.dev/configuration/fuzzy.html#rust-vs-lua-implementation) custom [fuzzy matcher](https://github.com/saghen/frizbee) for typo resistance. It provides extensibility via pluggable sources (LSP, buffer, snippets, etc), component based rendering and dynamic configuration.

<https://github.com/user-attachments/assets/bd1e25dd-48b0-4d33-90f4-1468d822f2be>

## Features

- Works out of the box with no additional configuration
- Updates on every keystroke (0.5-4ms async, single core)
- [Typo resistant fuzzy](https://github.com/saghen/frizbee) with frecency and proximity bonus
- Extensive LSP support ([tracker](https://cmp.saghen.dev/development/lsp-tracker))
- [Snippet support](https://cmp.saghen.dev/configuration/snippets.html): native `vim.snippet` (including `friendly-snippets`), `LuaSnip` and `mini.snippets`
- External sources support ([community sources](https://cmp.saghen.dev/configuration/sources.html#community-sources) and [compatibility layer for `nvim-cmp` sources](https://github.com/saghen/blink.compat))
- [Auto-bracket support](https://cmp.saghen.dev/configuration/completion.html#auto-brackets) based on semantic tokens
- [Signature help](https://cmp.saghen.dev/configuration/signature.html) (experimental, opt-in)
- [Command line completion](https://cmp.saghen.dev/modes/cmdline.html)
- [Terminal completion](https://cmp.saghen.dev/modes/term) (0.11+ only! No source for shell completions exists yet, contributions welcome!)
- [Comparison with built-in completion](https://cmp.saghen.dev/#compared-to-built-in-completion)
- [Comparison with nvim-cmp](https://cmp.saghen.dev/#compared-to-nvim-cmp)

## Installation

Head over to the [V1 documentation website](https://cmp.saghen.dev/installation) for installation instructions and configuration options.

For V2, use the [documentation website tracking `main`](https://main.cmp.saghen.dev/installation).

## Special Thanks

- [@hrsh7th](https://github.com/hrsh7th/) nvim-cmp used as inspiration and cmp-path/cmp-cmdline implementations modified for path/cmdline sources
- [@garymjr](https://github.com/garymjr) nvim-snippets implementation modified for snippets source
- [@redxtech](https://github.com/redxtech) Help with design and testing
- [@aaditya-sahay](https://github.com/aaditya-sahay) Help with rust, design and testing

### Contributors

- [@stefanboca](https://github.com/stefanboca) Author of [blink.compat](https://github.com/saghen/blink.compat) and maintainer
- [@soifou](https://github.com/soifou) Maintainer
- [@lopi-py](https://github.com/lopi-py) Windowing code
- [@scottmckendry](https://github.com/scottmckendry) CI and prebuilt binaries
- [@balssh](https://github.com/Balssh) + [@konradmalik](https://github.com/konradmalik) Nix flake, nixpkg and nixvim
- [@abeldekat](https://github.com/abeldekat) mini.snippets source
- [@FelipeLema](https://github.com/FelipeLema) vsnip source
- [@wurli](https://github.com/wurli) Terminal completions
- [@mikavilpas](https://github.com/mikavilpas) + [@xzbdmw](https://github.com/xzbdmw) Dot-repeat (`.`)
- [@FerretDetective](https://github.com/FerretDetective) `complete_func` source
- [@krovuxdev](https://github.com/krovuxdev) Community moderation and help

---

## File: doc/configuration/appearance.md

---
title: Appearance
---
# Appearance [Go to default configuration](./reference#appearance)

If you're looking for how to change the appearance of the completion menu, check out the [menu draw configuration](./completion#menu-draw).

## Highlight groups

| Group | Default | Description |
| ----- | ------- | ----------- |
| `BlinkCmpMenu` | Pmenu | The completion menu window |
| `BlinkCmpMenuBorder` | Pmenu | The completion menu window border |
| `BlinkCmpMenuSelection` | PmenuSel | The completion menu window selected item |
| `BlinkCmpScrollBarThumb` | PmenuThumb | The scrollbar thumb |
| `BlinkCmpScrollBarGutter` | PmenuSbar | The scrollbar gutter |
| `BlinkCmpLabel` | Pmenu | Label of the completion item |
| `BlinkCmpLabelDeprecated` | PmenuExtra | Deprecated label of the completion item |
| `BlinkCmpLabelMatch` | Pmenu | (Currently unused) Label of the completion item when it matches the query |
| `BlinkCmpLabelDetail` | PmenuExtra | Label description of the completion item |
| `BlinkCmpLabelDescription` | PmenuExtra | Label description of the completion item |
| `BlinkCmpKind` | PmenuKind | Kind icon/text of the completion item |
| `BlinkCmpKind<kind>` | PmenuKind | Kind icon/text of the completion item |
| `BlinkCmpSource` | PmenuExtra | Source of the completion item |
| `BlinkCmpGhostText` | NonText | Preview item with ghost text  |
| `BlinkCmpDoc` | NormalFloat | The documentation window |
| `BlinkCmpDocBorder` | NormalFloat | The documentation window border |
| `BlinkCmpDocSeparator` | NormalFloat | The documentation separator between doc and detail |
| `BlinkCmpDocCursorLine` | Visual | The documentation window cursor line |
| `BlinkCmpSignatureHelp` | NormalFloat | The signature help window |
| `BlinkCmpSignatureHelpBorder` | NormalFloat | The signature help window border |
| `BlinkCmpSignatureHelpActiveParameter` | LspSignatureActiveParameter | Active parameter of the signature help |

---

## File: doc/configuration/completion.md

# 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](./reference#completion-keyword)

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](./reference#completion-trigger)

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
```

<video src="https://github.com/user-attachments/assets/5e8f8f9f-bc6a-4d21-9cce-2e291b6a7de8" muted autoplay loop />
== 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
-- Optionally, set a list of characters that will not trigger the completion window,
-- even when sources request it. The following are the defaults:
completion.trigger.show_on_blocked_trigger_characters = { ' ', '\n', '\t' }
```

<video src="https://github.com/user-attachments/assets/b4ee0069-2de8-44e7-b3ca-51b10bc4cb4a" muted autoplay loop />
== 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
-- Optionally, set a list of characters that will not trigger the completion window,
-- even when sources request it. The following are the defaults:
completion.trigger.show_on_x_blocked_trigger_characters = {
  "'", '"', '(', '{', '['
}
```

<video src="https://github.com/user-attachments/assets/9e7aa3c2-4756-4a5e-a0e8-303d3ae0fda9" muted autoplay loop />
== 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
-- Optionally, set a list of characters that will not trigger the completion window,
-- even when sources request it. The following are the defaults:
completion.trigger.show_on_x_blocked_trigger_characters = { "'", '"', '(', '{', '[' }
```

Fires after accepting a path completion item, for example: `| -> foo/|`
:::



## List [Go to default configuration](./reference#completion-list)

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](../modes/cmdline.md) for more information.
:::

:::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 `<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`.

<video src="https://github.com/user-attachments/assets/ef295526-8332-4ad0-9a2a-e2f6484081b2" muted autoplay loop />

== 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.

You may use the `show_and_insert` keymap to show the completion menu and select the first item. The default keymap (`<C-space>`) uses the `show` command, which will not select the first item.

<video src="https://github.com/user-attachments/assets/09cd9b4b-18b3-456b-bb0a-074ae54e9d77" muted autoplay loop />
== 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 `<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 not select the first item.

<video src="https://github.com/user-attachments/assets/4658b61d-1b95-404a-b6b5-3a4afbfb8112" muted autoplay loop />
:::



To control the selection behavior dynamically, pass a function to `selection.preselect/auto_insert`:

```lua
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,
}
```


## Accept [Go to default configuration](./reference#completion-accept)

Manages the behavior when accepting an item in the completion menu.

### Auto Brackets

::: 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!

## Menu [Go to default configuration](./reference#completion-menu)

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](./reference#completion-menu-draw)

[Check out the recipes!](../recipes.md#completion-menu-drawing)

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.

If there are multiple components with `width.fill = true` then the space to be filled up is distributed equally between them. This can be used to e.g. center align a component.


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.

You can also set `overlap_components = true` in the config for your column to allow overlapping the columns of 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" } },
```

#### Available components

- `kind_icon`: Shows the icon for the kind of the item
- `kind`: 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)
  - If the `label_detail` is missing from your items, ensure you've [setup LSP capabilities](../installation) and that your LSP supports the feature
- `label_description`: Shows the label description of the item (e.g. `date-fns/formatDistance`, the module that the item will be auto-imported from)
  - If the `label_description` is missing from your items, ensure you've [setup LSP capabilities](../installation) and that your LSP supports the feature
- `source_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`)

#### Cursorline

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.

```lua
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`

```lua
completion.menu.draw.cursorline_priority = 0
```

### Treesitter

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.

```lua
completion.menu.draw.treesitter = { 'lsp' }
```

The wonderful [colorful-menu.nvim](https://github.com/xzbdmw/colorful-menu.nvim) takes this a step further by including context around the item before highlighting.

## Documentation [Go to default configuration](./reference#completion-documentation)

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`. You may completely override the drawing of the window via `completion.documentation.draw`.

## Ghost Text [Go to default configuration](./reference#completion-ghost-text)

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

-- 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
```

---

## File: doc/configuration/fuzzy.md

# Fuzzy

Blink uses a SIMD fuzzy matcher called [frizbee](https://github.com/saghen/frizbee) which achieves ~6x the performance of fzf while ignoring typos. Check out the repo for more information!

## Rust vs Lua implementation

Prebuilt binaries are included in the releases and automatically downloaded when on a release tag (see below). However, for unsupported systems or when the download fails, it will automatically fallback to a Lua implementation, emitting a warning. You may suppress this warning or enforce the Lua or Rust implementation.

- `prefer_rust_with_warning` If available, use the Rust implementation, automatically downloading prebuilt binaries on supported systems. Fallback to the Lua implementation when not available, emitting a warning message.
- `prefer_rust`: If available, use the Rust implementation, automatically downloading prebuilt binaries on supported systems. Fallback to the Lua implementation when not available.
- `rust`: Always use the Rust implementation, automatically downloading prebuilt binaries on supported systems. Error if not available.
- `lua`: Always use the Lua implementation

```lua
fuzzy = { implementation = "prefer_rust_with_warning" }
```

Prebuilt binaries are available for the following systems:
- Linux (glibc): x86_64 and aarch64
- Linux (musl): x86_64 and aarch64
- Linux (android / Termux): aarch64
- macOS: x86_64 and aarch64
- Windows: x86_64 and aarch64
- FreeBSD: x86_64 and aarch64
- OpenBSD: x86_64 and aarch64

### Advantages of Rust implementation

If possible, it's highly recommended to use the Rust implementation of the fuzzy matcher!

- Full unicode support
- Always finds the best match (resulting in better sorting)
- Performance on long lists (10k+ items)
- Typo resistance
- Proximity bonus
- Frecency

## Installation

### Prebuilt binaries (default on a release tag)

By default, Blink will download a prebuilt binary from the latest release, when you're on a release tag (via `version = '1.*'` on `lazy.nvim` for example). If you're not on a release tag (tracking `main` or some branch), you may force a specific version via `fuzzy.prebuilt_binaries.force_version = 'v1.9.1'` or glob `'v*'`. See [the latest release](https://github.com/saghen/blink.cmp/releases/latest) for supported systems. See `prebuilt_binaries` section of the [reference configuration](./reference.md#fuzzy) for more options.

You may instead install the prebuilt binaries manually by downloading the appropriate binary from the [latest release](https://github.com/saghen/blink.cmp/releases/latest) and placing it at `$data/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.$ext`. Get the `$data` path via `:echo stdpath('data')`. Use `.so` for linux, `.dylib` for mac, and `.dll` for windows. If you're unsure whether you want `-musl` or `-gnu` for linux, you very likely want `-gnu`.

> [!IMPORTANT]
> For the version verification to succeed, you must either ensure there is no `version` file adjacent to your `libblink_cmp_fuzzy` library or you must have `git` installed with the `.git` folder present in the `blink.cmp` directory

```sh
# Linux
~/.local/share/nvim/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.so

# Mac
~/.local/share/nvim/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.dylib

# Windows
~/Appdata/Local/nvim/lazy/blink.cmp/target/release/libblink_cmp_fuzzy.dll
```

### Build from source (recommended for `main`)

When on `main`, it's highly recommended to build from source via `require('blink.cmp').build():wait(60000)` (via `build = function() ... end` on `lazy.nvim` for example).

## Configuration

See the [fuzzy section of the reference configuration](./reference.md#fuzzy). For recipes, see [the recipes section](../recipes.md#fuzzy-sorting-filtering).

### Sorting

You can control how entries are sorted by choosing from several built-in sorting methods or by providing your own custom Lua function.

#### Built-in sorts

The following built-in sort strings are available:

- `exact`: Sorts by exact match, case-sensitive
- `score`: Sorts by the fuzzy matching score
- `sort_text`: Sorts by the `sortText` field
  - Generally, this field provides better sorting than `label` as the source/LSP may prioritize items relevant to the current context
  - If you're writing your own source, use this field to control sort order, instead of requiring users to add a sort function
- `label`: Sorts by the `label` field, deprioritizing entries with a leading `_`
- `kind`: Sorts by the numeric `kind` field
  - Check the order via `:lua vim.print(vim.lsp.protocol.CompletionItemKind)`

#### Sorting priority and tie-breaking

**The order in which you specify sorts in your configuration determines their priority.**

When sorting, each entry pair is compared using the first method in your list. If that comparison results in a tie, the next method is used, and so on. This allows you to build multi-level sorting logic.

```lua
fuzzy = {
  sorts = {
    'score',      -- Primary sort: by fuzzy matching score
    'sort_text',  -- Secondary sort: by sortText field if scores are equal
    'label',      -- Tertiary sort: by label if still tied
  }
}
```

In the example above:

- Entries are first sorted by score.
- If two entries have the same score, they are then sorted by sort_text.
- If still tied, they are sorted by label.

#### Sort list function

Instead of specifying a static list, you may also provide a function that returns a list of sorts.

```lua
fuzzy = {
  sorts = function()
    if vim.bo.filetype == "lua" then
      return { 'score', 'label' }  -- Prioritize label sorting for Lua files
    else
      return { 'score', 'sort_text', 'label' }  -- Default sorting for other filetypes
    end
  end,
}
```

#### Custom sorting

You may also provide a custom Lua function to define your own sorting logic. The function should follow the Lua [table.sort](https://www.lua.org/manual/5.1/manual.html#pdf-table.sort) convention.

```lua
fuzzy = {
  sorts = {
    -- example custom sorting function, ensuring `_` entries are always last (untested, YMMV)
    function(a, b)
        if a.label:sub(1, 1) == "_" ~= a.label:sub(1, 1) == "_" then
            -- return true to sort `a` after `b`, and vice versa
            return not a.label:sub(1, 1) == "_"
        end
        -- nothing returned, fallback to the next sort
    end,
    -- default sorts
    'score',
    'sort_text',
}
```

In the example above:

- The custom function is the primary sort: it puts entries starting with _ last.
- If two entries are equal according to the custom function, they are then sorted by score.
- If still tied, they are sorted by sort_text.

::: warning
If you are using the Rust implementation but specify a custom Lua function for sorting, the sorting process will fall back to Lua instead of being handled by Rust. This can impact performance, particularly when working with large lists.
:::

---

## File: doc/configuration/general.md

# General

Blink cmp has *a lot* of configuration options, the following code block highlights some changes you're most likely to care about. For more information, check out the additional pages.

For more common configurations, see the [recipes](../recipes.md).

::: warning
**Do not copy this entire configuration! It contains only non-default options**
:::

```
/* Detailed source-code truncated for AI context efficiency. */
```

---

## File: doc/configuration/keymap.md

# Keymap

**blink.cmp** provides a flexible and intuitive system for defining keymaps per Vim mode. You can use presets (predefined sensible mappings) or define your own mappings.

## Default configuration

```lua
-- Insert/Select mode
keymap = {
  preset = 'default',
},
-- Command-line mode
cmdline = {
    keymap = {
        preset = 'cmdline'
    }
}
-- Terminal mode
terminal = {
    keymap = {
        preset = 'terminal'
    }
}
```

## Presets overview

Choose any available preset that suits you best. See [all available presets](#presets) for a complete list of key mappings.

Special presets:

- `none`: No predefined mappings; define everything yourself (supported in all modes):

```lua
keymap = {
  preset = 'none',
  ['<C-Space>'] = { 'show' }, -- Only one command defined!
},
```

- `inherit`: Reuse mappings from the top-level keymap (**command-line & terminal only**)

```lua
keymap = {
  preset = 'default',
  ['<C-Space>'] = { 'show' },
},
cmdline = {
    keymap = {
        preset = 'inherit',
        --- <C-Space> inherited from top-level keymap
    }
}
```

See [cmdline documentation](../modes/cmdline.md) and [terminal documentation](../modes/term.md) for more details.

## Mapping syntax

```lua
['<key>'] = { action1, action2, action3 }
```

Each keymap maps a **key sequence** to a **list of actions** executed in order.

Actions can be either **commands** or **functions**:

- A **command** calls a public method available in `require('blink.cmp')`

    e.g., `show` → `require('blink.cmp').show(opts)`
- A **function** runs custom logic with access to the `cmp` object

**Execution flow**: Actions are executed sequentially. If an action returns `false`, `nil` or `''`, **execution continues** to the next action. Any other return value **stops execution**.

::: warning
Forgetting to return a value in a function implicitly returns `nil`, which may cause unintended fallbacks. Always explicitly return a value to control fallback behavior.
:::

Example with conditional logic:

```lua
['<C-n>'] = {
  function(cmp)
    if condition_1 then
      -- Continue to next action
      return false -- or '' or nil
    end

    if condition_2 then
      -- Run `show` command
      -- Stop execution if returning true
      return cmp.show()
    end

    if condition_3 then
      -- Returned string is passed to feedkeys() with 't' flag (remap enabled)
      -- User mappings take precedence over built-in behavior
      -- Doesn't run next action
      return '<CR>'
    end

    -- Stop execution
    return true
  end,
  -- Next command
  'select_next',
  -- Fallback to non-blink mapping
  -- See :imap <C-n>
  'fallback',
},
```

## Full example

 ```lua
keymap = {
  preset = 'default',

  -- Single command
  ['<C-n>'] = { 'select_next' },

  -- Chained commands
  ['<C-p>'] = { 'select_prev', 'fallback' },

  -- Multi-key sequences
  ['<C-x><C-o>'] = { 'show', 'fallback' },
  ['jk'] = { 'hide' },

  -- Key equivalences (for terminals that support them)
  ['<C-i>'] = { 'accept', 'snippet_forward', 'fallback' },
  ['<Tab>'] = { 'select_next', 'fallback' },

  -- Override preset key
  ['<C-y>'] = { 'select_and_accept' },

  -- Disable preset key
  ['<C-e>'] = false, -- or {}

  -- Function calling blink.cmp method
  ['<C-Space>'] = { function(cmp) return cmp.show() end },
  ['<C-Space>'] = { 'show' }, -- This is equivalent as above

  -- Actions with parameters require functions
  ['<C-space>S'] = { function(cmp) return cmp.show({ providers = { 'snippets' } }) end },

  -- String returns - feedkeys() with 't' flag (remap enabled)
  -- User mappings take precedence over built-in behavior
  ['<C-n>'] = { 'select_next' },
  -- Here, <C-n> triggers 'select_next' command defined above
  ['<C-j>'] = { function(cmp) return '<C-n>' end },
}
 ```

## Commands

This lists all available **blink.cmp** commands, grouped by category for clarity.
Click any command below to expand its full details, parameters, and examples.

### Completion Menu

::: details `show` - Shows the completion menu

#### Parameters

- `providers`: Show with a specific list of providers
- `initial_selected_item_idx`: The index of the item to select initially
- `callback`: Runs a function after the menu is shown

#### Example

```lua
function(cmp)
  return cmp.show({
    providers = { "snippets" },
  })
end
```

:::

::: details `show_and_insert` - Shows completion menu and inserts first item
When `auto_insert = true`, short form for:

```lua
function(cmp)
  return cmp.show({ initial_selected_item_idx = 1 })
end
```

#### Parameters

- `providers`: Show with a specific list of providers.
- `initial_selected_item_idx`: The index of the item to select initially. Defaults to `1`.
- `callback`: Runs a function after the menu is shown.

#### Example

```lua
function(cmp)
  return cmp.show_and_insert({
    providers = { "snippets" },
  })
end
```

:::

::: details `show_and_insert_or_accept_single` - Shows completion menu and inserts first item, or accepts if single
Shows the completion menu and inserts the first item, or accepts the first item if there is only one.

#### Parameters

- `providers`: Show with a specific list of providers
- `initial_selected_item_idx`: The index of the item to select initially
- `callback`: Runs a function after the menu is shown

#### Example

```lua
function(cmp)
  return cmp.show_and_insert_or_accept_single({
    providers = { "snippets" },
  })
end
```

:::

::: details `hide` - Hides the completion menu

#### Parameters

- `callback`: Runs a function after the menu is hidden.

#### Example

```lua
function(cmp)
  return cmp.hide({
    callback = function() some_function() end,
  })
end
```

:::

::: details `cancel` - Reverts auto_insert and hides the menu
Reverts `completion.list.selection.auto_insert` and hides the completion menu.

#### Parameters

- `callback`: Runs a function after the menu is hidden.

#### Example

```lua
function(cmp)
  return cmp.cancel({
    callback = function() some_function() end,
  })
end
```

:::

### Accepting Items

::: details `accept` - Accepts the currently selected item

#### Parameters

- `index`: Select a specific item by index.
- `force`: Accept without visual feedback (no menu, no ghost text).
- `callback`: Run a function after the item is accepted.

#### Example

```lua
-- Accept first item
function(cmp) return cmp.accept({ index = 1 }) end

-- Force accept silently
function(cmp) return cmp.accept({ force = true }) end

-- Accept then trigger callback
function(cmp)
  return cmp.accept({
    callback = function() some_function() end,
  })
end
```

:::

::: details `accept_and_enter` - Accepts the item and sends `<Enter>` key
Accepts the currently selected item and feeds an enter key to Neovim.

Useful in `cmdline` mode to accept and execute a command.

#### Parameters

- `force`: Force accept without visual feedback (no menu, no ghost text visible)
- `callback`: Run a function after the item is accepted.

#### Example

```lua
-- Force accept silently
function(cmp) return cmp.accept_and_enter({ force = true }) end

-- Accept then trigger callback
function(cmp)
  return cmp.accept_and_enter({
    callback = function() some_function() end,
  })
end
```

:::

::: details `select_and_accept` - Accepts selected or first item
Accepts the currently selected item, or the first item if none is selected.

#### Parameters

- `force`: Force accept without visual feedback (no menu, no ghost text visible)
- `callback`: Run a function after the item is accepted.

#### Example

```lua
-- Force accept silently
function(cmp) return cmp.select_and_accept({ force = true }) end

-- Accept then trigger callback
function(cmp)
  return cmp.select_and_accept({
    callback = function() some_function() end,
  })
end
```

:::

::: details `select_accept_and_enter` - Accepts item and sends `<Enter>` key
Accepts the currently selected or first item and feeds an enter key to Neovim.

Useful in `cmdline` mode to execute directly.

#### Parameters

- `force`: Force accept without visual feedback (no menu, no ghost text visible).
- `callback`: Run a function after the item is accepted.

#### Example

```lua
-- Force accept silently
function(cmp) return cmp.select_accept_and_enter({ force = true }) end

-- Accept then trigger callback
function(cmp)
  return cmp.select_accept_and_enter({
    callback = function() some_function() end,
  })
end
```

:::

### Navigation

::: details `select_prev` - Selects previous item in the completion list

#### Parameters

- `count`: Number of items to jump by (default `1`).
- `auto_insert`: Insert the completion item automatically when selecting it. Control `completion.list.selection.auto_insert`.
- `jump_by`:  Jump to previous item with different value in specified property: `client_id`, `client_name`, `deprecated`, `exact`, `kind`, `score`, `score_offset`, `source_id`, `source_name`.
- `on_ghost_text`: Run a function when ghost text is visible.

#### Example

```lua
-- Jump five items up
function(cmp) return cmp.select_prev({ count = 5 }) end

-- Select without inserting
function(cmp) return cmp.select_prev({ auto_insert = false }) end
```

:::

::: details `select_next` - Selects next item in the completion list

#### Parameters

- `count`: Number of items to jump by (default `1`).
- `auto_insert`: Insert the completion item automatically when selecting it. Control `completion.list.selection.auto_insert`.
- `jump_by`:  Jump to next item with different value in specified property: `client_id`, `client_name`, `deprecated`, `exact`, `kind`, `score`, `score_offset`, `source_id`, `source_name`.
- `on_ghost_text`: Run a function when ghost text is visible.

#### Example

```lua
-- Jump five items down
function(cmp) return cmp.select_next({ count = 5 }) end

-- Select without inserting
function(cmp) return cmp.select_next({ auto_insert = false }) end
```

:::

::: details `insert_prev` - Inserts previous item
Inserts the previous item (`auto_insert`), cycling to the bottom if at the top, if `completion.list.cycle.from_top == true`.
This will trigger completions if none are available, unlike `select_prev` which would fallback to the next keymap in this case.

No parameters.
:::

::: details `insert_next` - Inserts next item
Inserts the next item (`auto_insert`), cycling to the top of the list if at the bottom, if `completion.list.cycle.from_bottom == true`.
This will trigger completions if none are available, unlike `select_next` which would fallback to the next keymap in this case.

No parameters.
:::

### Documentation Window

::: details `show_documentation` - Shows documentation for the selected item
No parameters.
:::

::: details `hide_documentation` - Hides documentation for the selected item
No parameters.
:::

::: details `scroll_documentation_up` - Scrolls documentation up

#### Parameters

- `count`: Number of lines to scroll (default `4`).

#### Example

```lua
function(cmp) return cmp.scroll_documentation_up(4) end
```

:::

::: details `scroll_documentation_down` - Scrolls documentation down

#### Parameters

- `count`: Number of lines to scroll (default `4`).

#### Example

```lua
function(cmp) return cmp.scroll_documentation_down(4) end
```

:::

### Signature Help

::: details `show_signature` - Shows the signature help window
No parameters.
:::

::: details `hide_signature` - Hides the signature help window
No parameters.
:::

::: details `scroll_signature_up` - Scrolls the signature help up

#### Parameters

- `count`: Number of lines to scroll (default `4`).

#### Example

```lua
function(cmp) return cmp.scroll_signature_up(4) end
```

:::

::: details `scroll_signature_down` - Scrolls the signature help down

#### Parameters

- `count`: Number of lines to scroll (default `4`).

#### Example

```lua
function(cmp) return cmp.scroll_signature_down(4) end
```

:::

### Snippets

::: details `snippet_forward` - Jumps to the next snippet placeholder
No parameters.
:::

::: details `snippet_backward` - Jumps to the previous snippet placeholder
No parameters.
:::

### Fallback

::: details `fallback` - Runs the next non-blink keymap
Runs the next non-blink keymap, or invokes the built-in Neovim binding.

No parameters.
:::

::: details `fallback_to_mappings` - Runs next non-blink keymap (not built-in)
Runs the next non-blink keymap (not built-in behavior).

No parameters.
:::

## Presets

### `default`

```lua
['<C-space>'] = { 'show', 'show_documentation', 'hide_documentation' },
['<C-e>'] = { 'hide', 'fallback' },
['<C-y>'] = { 'select_and_accept', 'fallback' },

[''] = { 'select_prev', 'fallback' },
['<Down>'] = { 'select_next', 'fallback' },
['<C-p>'] = { 'select_prev', 'fallback_to_mappings' },
['<C-n>'] = { 'select_next', 'fallback_to_mappings' },

['<C-b>'] = { 'scroll_documentation_up', 'fallback' },
['<C-f>'] = { 'scroll_documentation_down', 'fallback' },

['<Tab>'] = { 'snippet_forward', 'fallback' },
['<S-Tab>'] = { 'snippet_backward', 'fallback' },

['<C-k>'] = { 'show_signature', 'hide_signature', 'fallback' },
```

### `super-tab`

::: info
You may want to set `completion.trigger.show_in_snippet = false` or use:

```lua
completion.list.selection.preselect = function(ctx)
    return not require('blink.cmp').snippet_active({ direction = 1 })
end
```

See more info in [`completion.list`](../configuration/completion.md#list).
:::

```lua
['<C-space>'] = { 'show', 'show_documentation', 'hide_documentation' },
['<C-e>'] = { 'hide', 'fallback' },

['<Tab>'] = {
  function(cmp)
    if cmp.snippet_active() then return cmp.accept()
    else return cmp.select_and_accept() end
  end,
  'snippet_forward',
  'fallback'
},
['<S-Tab>'] = { 'snippet_backward', 'fallback' },

[''] = { 'select_prev', 'fallback' },
['<Down>'] = { 'select_next', 'fallback' },
['<C-p>'] = { 'select_prev', 'fallback_to_mappings' },
['<C-n>'] = { 'select_next', 'fallback_to_mappings' },

['<C-b>'] = { 'scroll_documentation_up', 'fallback' },
['<C-f>'] = { 'scroll_documentation_down', 'fallback' },

['<C-k>'] = { 'show_signature', 'hide_signature', 'fallback' },
```

### `enter`

::: info
You may want to set `completion.list.selection.preselect = false`.

See more info in [`completion.list`](../configuration/completion.md#list).
:::

```lua
['<C-space>'] = { 'show', 'show_documentation', 'hide_documentation' },
['<C-e>'] = { 'hide', 'fallback' },
['<CR>'] = { 'accept', 'fallback' },

['<Tab>'] = { 'snippet_forward', 'fallback' },
['<S-Tab>'] = { 'snippet_backward', 'fallback' },

[''] = { 'select_prev', 'fallback' },
['<Down>'] = { 'select_next', 'fallback' },
['<C-p>'] = { 'select_prev', 'fallback_to_mappings' },
['<C-n>'] = { 'select_next', 'fallback_to_mappings' },

['<C-b>'] = { 'scroll_documentation_up', 'fallback' },
['<C-f>'] = { 'scroll_documentation_down', 'fallback' },

['<C-k>'] = { 'show_signature', 'hide_signature', 'fallback' },
```

### `cmdline`

```lua
{
  -- optionally, inherit the mappings from the top level `keymap`
  -- instead of using the neovim defaults
  -- preset = 'inherit',

  ['<Tab>'] = { 'show_and_insert_or_accept_single', 'select_next' },
  ['<S-Tab>'] = { 'show_and_insert_or_accept_single', 'select_prev' },

  ['<C-space>'] = { 'show', 'fallback' },

  ['<C-n>'] = { 'select_next', 'fallback' },
  ['<C-p>'] = { 'select_prev', 'fallback' },
  ['<Right>'] = { 'select_next', 'fallback' },
  ['<Left>'] = { 'select_prev', 'fallback' },

  ['<C-y>'] = { 'select_and_accept', 'fallback' },
  ['<C-e>'] = { 'cancel', 'fallback' },
}
```

---

## File: doc/configuration/reference.md

# Reference

::: warning
Do not copy the default configuration! Only include options you want to change in your configuration
:::

```lua
-- Enables keymaps, completions and signature help when true (doesn't apply to cmdline or term)
--
-- If the function returns 'force', the default conditions for disabling the plugin will be ignored
-- Default conditions: (vim.bo.buftype ~= 'prompt' and vim.b.completion ~= false)
-- Note that the default conditions are ignored when `vim.b.completion` is explicitly set to `true`
--
-- Exceptions: vim.bo.filetype == 'dap-repl'
enabled = function() return true end,

-- See the "keymap" page for more information
keymap = { preset = 'default' },
```

## Snippets

```lua
snippets = {
  -- Function to use when expanding LSP provided snippets
  expand = function(snippet) vim.snippet.expand(snippet) end,
  -- Function to use when checking if a snippet is active
  active = function(filter) return vim.snippet.active(filter) end,
  -- Function to use when jumping between tab stops in a snippet, where direction can be negative or positive
  jump = function(direction) vim.snippet.jump(direction) end,
}
```

## Completion

### Completion Keyword

```lua
completion.keyword = {
  -- 'prefix' will fuzzy match on the text before the cursor
  -- 'full' will fuzzy match on the text before _and_ after the cursor
  -- example: 'foo_|_bar' will match 'foo_' for 'prefix' and 'foo__bar' for 'full'
  range = 'prefix',
}
```

### Completion Trigger

```
/* Detailed source-code truncated for AI context efficiency. */
```

### Completion List

```lua
completion.list = {
  -- Maximum number of items to display
  max_items = 200,

  selection = {
    -- When `true`, will automatically select the first item in the completion list
    preselect = true,
    -- preselect = function(ctx) return vim.bo.filetype ~= 'markdown' end,

    -- When `true`, inserts the completion item automatically when selecting it
    -- You may want to bind a key to the `cancel` command (default <C-e>) when using this option,
    -- which will both undo the selection and hide the completion menu
    auto_insert = true,
    -- auto_insert = function(ctx) return vim.bo.filetype ~= 'markdown' end
  },

  cycle = {
    -- When `true`, calling `select_next` at the _bottom_ of the completion list
    -- will select the _first_ completion item.
    from_bottom = true,
    -- When `true`, calling `select_prev` at the _top_ of the completion list
    -- will select the _last_ completion item.
    from_top = true,
  },
},
```

### Completion Accept

```lua
completion.accept = {
  -- Write completions to the `.` register
  dot_repeat = true,
  -- Create an undo point when accepting a completion item
  create_undo_point = true,
  -- How long to wait for the LSP to resolve the item with additional information before continuing as-is
  resolve_timeout_ms = 100,
  -- Experimental auto-brackets support
  auto_brackets = {
    -- Whether to auto-insert brackets for functions
    enabled = true,
    -- Default brackets to use for unknown languages
    default_brackets = { '(', ')' },
    -- Overrides the default blocked filetypes
    -- See: https://github.com/Saghen/blink.cmp/blob/main/lua/blink/cmp/completion/brackets/config.lua#L5-L9
    override_brackets_for_filetypes = {},
    -- Synchronously use the kind of the item to determine if brackets should be added
    kind_resolution = {
      enabled = true,
      blocked_filetypes = { 'typescriptreact', 'javascriptreact', 'vue' },
    },
    -- Asynchronously use semantic token to determine if brackets should be added
    semantic_token_resolution = {
      enabled = true,
      blocked_filetypes = { 'java' },
      -- How long to wait for semantic tokens to return before assuming no brackets should be added
      timeout_ms = 400,
    },
  },
},
```

### Completion Menu

```lua
completion.menu = {
  enabled = true,
  min_width = 15,
  max_height = 10,
  border = nil, -- Defaults to `vim.o.winborder` on nvim 0.11+
  winblend = 0,
  winhighlight = 'Normal:BlinkCmpMenu,FloatBorder:BlinkCmpMenuBorder,CursorLine:BlinkCmpMenuSelection,Search:None,CurSearch:None',
  -- Keep the cursor X lines away from the top/bottom of the window
  scrolloff = 2,
  -- Note that the gutter will be disabled when border ~= 'none'
  scrollbar = true,
  -- Which directions to show the window,
  -- falling back to the next direction when there's not enough space
  direction_priority = { 's', 'n' },
  -- Can accept a function if you need more control
  -- direction_priority = function()
  --   if condition then return { 'n', 's' } end
  --   return { 's', 'n' }
  -- end,

  -- Whether to automatically show the window when new completion items are available
  auto_show = true,
  -- Delay before showing the completion menu
  auto_show_delay_ms = 0,

  -- Screen coordinates of the command line
  cmdline_position = function()
    if vim.g.ui_cmdline_pos ~= nil then
      local pos = vim.g.ui_cmdline_pos -- (1, 0)-indexed
      return { pos[1] - 1, pos[2] }
    end
    local height = (vim.o.cmdheight == 0) and 1 or vim.o.cmdheight
    return { vim.o.lines - height, 0 }
  end,
}
```

### Completion Menu Draw

```
/* Detailed source-code truncated for AI context efficiency. */
```

### Completion Documentation

```lua
completion.documentation = {
  -- Controls whether the documentation window will automatically show when selecting a completion item
  auto_show = false,
  -- Delay before showing the documentation window
  auto_show_delay_ms = 500,
  -- Delay before updating the documentation window when selecting a new item,
  -- while an existing item is still visible
  update_delay_ms = 50,
  -- Whether to use treesitter highlighting, disable if you run into performance issues
  treesitter_highlighting = true,
  -- Draws the item in the documentation window, by default using an internal treesitter based implementation
  draw = function(opts) opts.default_implementation() end,
  window = {
    min_width = 10,
    max_width = 80,
    max_height = 20,
    border = nil, -- Defaults to `vim.o.winborder` on nvim 0.11+ or 'padded' when not defined/<=0.10
    winblend = 0,
    winhighlight = 'Normal:BlinkCmpDoc,FloatBorder:BlinkCmpDocBorder,EndOfBuffer:BlinkCmpDoc',
    -- Note that the gutter will be disabled when border ~= 'none'
    scrollbar = true,
    -- Which directions to show the documentation window,
    -- for each of the possible menu window directions,
    -- falling back to the next direction when there's not enough space
    direction_priority = {
      menu_north = { 'e', 'w', 'n', 's' },
      menu_south = { 'e', 'w', 's', 'n' },
    },
  },
}
```

### Completion Ghost Text

```lua
-- Displays a preview of the selected item on the current line
completion.ghost_text = {
  enabled = false,
  -- Show the ghost text when an item has been selected
  show_with_selection = true,
  -- Show the ghost text when no item has been selected, defaulting to the first item
  show_without_selection = false,
  -- Show the ghost text when the menu is open
  show_with_menu = true,
  -- Show the ghost text when the menu is closed
  show_without_menu = true,
  -- Only show the first line of ghost text for multi-line suggestions
  show_first_line_only = false,
},
```

## Signature

```lua
-- Experimental signature help support
signature = {
  enabled = false,
  trigger = {
    -- Show the signature help automatically
    enabled = true,
    -- Show the signature help window after typing any of alphanumerics, `-` or `_`
    show_on_keyword = false,
    blocked_trigger_characters = {},
    blocked_retrigger_characters = {},
    -- Show the signature help window after typing a trigger character
    show_on_trigger_character = true,
    -- Show the signature help window when entering insert mode
    show_on_insert = false,
    -- Show the signature help window when the cursor comes after a trigger character when entering insert mode
    show_on_insert_on_trigger_character = true,
  },
  window = {
    min_width = 1,
    max_width = 100,
    max_height = 10,
    border = nil, -- Defaults to `vim.o.winborder` on nvim 0.11+ or 'padded' when not defined/<=0.10
    winblend = 0,
    winhighlight = 'Normal:BlinkCmpSignatureHelp,FloatBorder:BlinkCmpSignatureHelpBorder',
    scrollbar = false, -- Note that the gutter will be disabled when border ~= 'none'
    -- Which directions to show the window,
    -- falling back to the next direction when there's not enough space,
    -- or another window is in the way
    direction_priority = { 'n', 's' },
    -- Can accept a function if you need more control
    -- direction_priority = function()
    --   if condition then return { 'n', 's' } end
    --   return { 's', 'n' }
    -- end,

    -- Disable if you run into performance issues
    treesitter_highlighting = true,
    show_documentation = true,
  },
}
```

## Fuzzy

```
/* Detailed source-code truncated for AI context efficiency. */
```

## Sources

See the [mode specific configurations](#mode-specific) for setting sources for `cmdline` and `term`.

```lua
sources = {
  -- Static list of providers to enable, or a function to dynamically enable/disable providers based on the context
  default = { 'lsp', 'path', 'snippets', 'buffer' },

  -- You may also define providers per filetype
  per_filetype = {
    -- optionally inherit from the `default` sources
    -- lua = { inherit_defaults = true, 'lsp', 'path' },
    -- vim = { inherit_defaults = true, 'cmdline' },
  },

  -- Function to use when transforming the items before they're returned for all providers
  -- The default will lower the score for snippets to sort them lower in the list
  transform_items = function(_, items) return items end,

  -- Minimum number of characters in the keyword to trigger all providers
  -- May also be `function(ctx: blink.cmp.Context): number`
  min_keyword_length = 0,
}
```

### Providers

```
/* Detailed source-code truncated for AI context efficiency. */
```

## Appearance

```lua
appearance = {
  highlight_ns = vim.api.nvim_create_namespace('blink_cmp'),
  -- Sets the fallback highlight groups to nvim-cmp's highlight groups
  -- Useful for when your theme doesn't support blink.cmp
  -- Will be removed in a future release
  use_nvim_cmp_as_default = false,
  -- Set to 'mono' for 'Nerd Font Mono' or 'normal' for 'Nerd Font'
  -- Adjusts spacing to ensure icons are aligned
  nerd_font_variant = 'mono',
  kind_icons = {
    Text = '󰉿',
    Method = '󰊕',
    Function = '󰊕',
    Constructor = '󰒓',

    Field = '󰜢',
    Variable = '󰆦',
    Property = '󰖷',

    Class = '󱡠',
    Interface = '󱡠',
    Struct = '󱡠',
    Module = '󰅩',

    Unit = '󰪚',
    Value = '󰦨',
    Enum = '󰦨',
    EnumMember = '󰦨',

    Keyword = '󰻾',
    Constant = '󰏿',

    Snippet = '󱄽',
    Color = '󰏘',
    File = '󰈔',
    Reference = '󰬲',
    Folder = '󰉋',
    Event = '󱐋',
    Operator = '󰪚',
    TypeParameter = '󰬛',
  },
}
```

## Mode specific

You may set configurations which will override the default configuration, specifically for that mode. Only properties in the top level config that support `fun()` may be overridden, as well as `sources` and `keymap`.

### Cmdline

```lua
cmdline = {
  enabled = true,
  -- use 'inherit' to inherit mappings from top level `keymap` config
  keymap = { preset = 'cmdline' },
  sources = { 'buffer', 'cmdline' },

  -- OR explicitly configure per cmd type
  -- This ends up being equivalent to above since the sources disable themselves automatically
  -- when not available. You may override their `enabled` functions via
  -- `sources.providers.cmdline.override.enabled = function() return your_logic end`

  -- sources = function()
  --   local type = vim.fn.getcmdtype()
  --   -- Search forward and backward
  --   if type == '/' or type == '?' then return { 'buffer' } end
  --   -- Commands
  --   if type == ':' or type == '@' then return { 'cmdline', 'buffer' } end
  --   return {}
  -- end,

  completion = {
    trigger = {
      show_on_blocked_trigger_characters = {},
      show_on_x_blocked_trigger_characters = {},
    },
    list = {
      selection = {
        -- When `true`, will automatically select the first item in the completion list
        preselect = true,
        -- When `true`, inserts the completion item automatically when selecting it
        auto_insert = true,
      },
    },
    -- Whether to automatically show the window when new completion items are available
    -- Default is false for cmdline, true for cmdwin (command-line window)
    menu = { auto_show = function(ctx, _) return ctx.mode == 'cmdwin' end },
    -- Displays a preview of the selected item on the current line
    ghost_text = { enabled = true },
  }
}
```

### Terminal

::: warning
Terminal completions are 0.11+ only! Known bugs in v0.10
:::

```lua
term = {
  enabled = false,
  keymap = { preset = 'inherit' }, -- Inherits from top level `keymap` config when not set
  sources = {},
  completion = {
    trigger = {
      show_on_blocked_trigger_characters = {},
      show_on_x_blocked_trigger_characters = nil, -- Inherits from top level `completion.trigger.show_on_blocked_trigger_characters` config when not set
    },
    -- Inherits from top level config options when not set
    list = {
      selection = {
        -- When `true`, will automatically select the first item in the completion list
        preselect = nil,
        -- When `true`, inserts the completion item automatically when selecting it
        auto_insert = nil,
      },
    },
    -- Whether to automatically show the window when new completion items are available
    menu = { auto_show = nil },
    -- Displays a preview of the selected item on the current line
    ghost_text = { enabled = nil },
  }
}
```

---

## File: doc/configuration/signature.md

---
title: Signature
---
# Signature [Go to default configuration](./reference#signature)

::: info
This feature is _experimental_, [contributions welcome](https://github.com/Saghen/blink.cmp/issues/1071)!
:::

Blink supports signature help by manually pressing `<C-k>` (by default) or automatically triggered when typing trigger characters, defined by the LSP, such as `(` for `lua`. The menu will be updated when pressing a retrigger character, such as `,`. Due to it being experimental, this feature is opt-in.

```lua
signature = { enabled = true }
```



You may want to set `signature.window.show_documentation = false` to only show the signature, and not the documentation.

## Keymap

See the [keymap documentation](../modes/cmdline.md#keymap) for a full list of commands. By default, the `scroll_signature_up` and `scroll_signature_down` commands are not bound to any keys. You may bind them like so:

```lua
keymap = {
  ['<C-u>'] = { 'scroll_signature_up', 'fallback' },
  ['<C-d>'] = { 'scroll_signature_down', 'fallback' },

  -- default in all keymap presets
  ['<C-k>'] = { 'show_signature', 'hide_signature', 'fallback' },
}
```

---

## File: doc/configuration/snippets.md

---
title: Snippets
---
# Snippets [Go to default configuration](./reference#snippets)

Blink uses the `vim.snippet` API by default for expanding and navigating snippets. The built-in `snippets` source will load [friendly-snippets](https://github.com/rafamadriz/friendly-snippets), if available, and load any snippets found at `~/.config/nvim/snippets/`. For use with Luasnip, see the [Luasnip section](#luasnip). For use with mini.snippets, see the [mini.snippets section](#mini-snippets). For use with vim-vsnip, see the [vim-vsnip section](#vim-vsnip).

## Friendly Snippets

When using the built-in `vim.snippet` snippet engine, [friendly-snippets](https://github.com/rafamadriz/friendly-snippets) will be automatically loaded, if available (disable with `friendly_snippets = false`). To [add snippets from a framework to a filetype](https://github.com/rafamadriz/friendly-snippets?tab=readme-ov-file#add-snippets-from-a-framework-to-a-filetype) use `extended_filetypes`.

```lua
sources = {
  providers = {
    snippets = {
      opts = {
        friendly_snippets = true, -- default

        -- see the list of frameworks in: https://github.com/rafamadriz/friendly-snippets/tree/main/snippets/frameworks
        -- and search for possible languages in: https://github.com/rafamadriz/friendly-snippets/blob/main/package.json
        -- the following is just an example, you should only enable the frameworks that you use
        extended_filetypes = {
          markdown = { 'jekyll' },
          sh = { 'shelldoc' },
          php = { 'phpdoc' },
          cpp = { 'unreal' }
        }
      }
    }
  }
}
```

To filter which snippets are shown, use `filter_snippets` which provides the filetype
and name of the snippets file. This function returns `true` if the snippet
should be included in completion results, and `false` if it should be filtered out.

```lua
sources = {
  providers = {
    snippets = {
      opts = {
        -- disable friendly-snippets frameworks
        filter_snippets = function(ft, file)
          return not (string.match(file, "friendly.snippets") and string.match(file, "framework"))
        end,
      }
    }
  }
}

```

## Custom snippets

By default, the `snippets` source will check `~/.config/nvim/snippets` for your custom snippets, but you may add additional folders via `sources.providers.snippets.opts.search_paths`. Currently, only VSCode style snippets are supported, but you may look into [Luasnip](https://github.com/L3MON4D3/LuaSnip) if you'd like more advanced functionality. If you're coming from snipmate snippets, [nadiamoe](https://github.com/nadiamoe) wrote [a small tool for converting them to JSON](https://github.com/nadiamoe/snipmate-to-json) (here be dragons! [original discussion](https://github.com/Saghen/blink.cmp/discussions/654#discussioncomment-12083447))

There's a great introduction to writing custom snippets [in the nvim-scissors repo](https://github.com/chrisgrieser/nvim-scissors?tab=readme-ov-file#cookbook--faq). Here's an example, using the linux/mac path for the neovim configuration:

```jsonc
// ~/.config/nvim/snippets/package.json
{
  "name": "personal-snippets",
  "contributes": {
    "snippets": [
      { "language": "lua", "path": "./lua.json" }
      { "language": ["typescriptreact", "javascriptreact"], "path": "./react.json" }
      { "language": "all", "path": "./all.json" }
    ]
  }
}
```

```jsonc
// ~/.config/nvim/snippets/lua.json
{
  "foo": {
    "prefix": "foo",
    "body": [
      "local ${1:foo} = ${2:bar}",
      "return ${3:baz}"
    ]
  }
}
```

## Luasnip

```lua
{
  'saghen/blink.cmp',
  dependencies = { 'L3MON4D3/LuaSnip' },
  opts = {
    snippets = { preset = 'luasnip' },
    -- ensure you have the `snippets` source (enabled by default)
    sources = {
      default = { 'lsp', 'path', 'snippets', 'buffer' },
    },
  }
}
```

## `mini.snippets`

```lua
{
  'saghen/blink.cmp',
  dependencies = { 'echasnovski/mini.snippets' },
  opts = {
    snippets = { preset = 'mini_snippets' },
    -- ensure you have the `snippets` source (enabled by default)
    sources = {
      default = { 'lsp', 'path', 'snippets', 'buffer' },
    },
  }
}
```

## `vim-vsnip`

```lua
{
  'saghen/blink.cmp',
  dependencies = { 'hrsh7th/vim-vsnip', 'https://codeberg.org/FelipeLema/bink-cmp-vsnip.git' },
  opts = {
    snippets = { preset = 'vsnip' },
    -- ensure you have the `snippets` source (enabled by default)
    sources = {
      default = { 'lsp', 'path', 'snippets', 'buffer' },
    },
  }
}
```

## Disable all snippets

```lua
sources.transform_items = function(_, items)
  return vim.tbl_filter(function(item)
    return item.kind ~= require('blink.cmp.types').CompletionItemKind.Snippet
  end, items)
end
```

When setting up your capabilities with `lspconfig`, add the following:

```lua
capabilities = require('blink.cmp').get_lsp_capabilities({
  textDocument = { completion = { completionItem = { snippetSupport = false } } },
})
```

Some LSPs may ignore the `snippetSupport` field, in which case, you need to set LSP specific options while setting them up. Some examples:

```lua
-- If you're using `opts = { ['rust-analyzer'] = { } }` in your lspconfig configuration, simply put these options in there instead

-- For `rust-analyzer`
lspconfig['rust-analyzer'].setup({
  settings = {
    ['rust-analyzer'] = {
      completion = {
        callable = {
          -- https://rust-analyzer.github.io/book/configuration.html#completion.callable.snippets
          snippets = 'add_parentheses', -- or 'none'
        },
      },
    },
  },
})

-- For `lua_ls`
lspconfig.lua_ls.setup({
  settings = {
    Lua = {
      completion = {
        callSnippet = 'Disable',
        keywordSnippet = 'Disable',
      }
    }
  }
})
```

Please open a PR if you know of any other LSPs that require special configuration!

---

## File: doc/configuration/sources.md

---
title: Sources
---
# Sources [Go to default configuration](./reference#sources)
::: info
Check out the [recipes](../recipes.md#sources) for some common configurations
:::

Blink provides a sources interface, modelled after LSPs, for getting completion items, trigger characters, documentation and signature help. The `lsp`, `path`, `snippets`, `buffer`, and `omni` sources are built-in. You may add additional [community sources](#community-sources) as well. Check out the [source boilerplate](../development/source-boilerplate.md) to learn how to write your own!

## Providers

Sources are configured via the `sources.providers` table, where each `id` (`key`) must have a `name` and `module` field. The `id` (`key`) may be used in the `sources.default/per_filetype`, `cmdline.sources`, and `term.sources` to enable the source.

See the [reference](./reference.md#sources) for the default configuration options.

```lua
sources = {
  -- `lsp`, `buffer`, `snippets`, `path` and `omni` are built-in
  -- so you don't need to define them in `sources.providers`
  default = { 'lsp', 'buffer', 'snippets', 'path' },

  per_filetype = {
    sql = { 'dadbod' },
    -- optionally inherit from the `default` sources
    lua = { inherit_defaults = true, 'lazydev' }
  },
  providers = {
    dadbod = { module = "vim_dadbod_completion.blink" },
    lazydev = { ... }
  }
}
```

### Provider options

All of the fields shown below apply to all sources. The `opts` field is passed to the source directly, and will vary by source.

```lua
sources.providers.lsp = {
  name = 'LSP',
  module = 'blink.cmp.sources.lsp',
  opts = {}, -- Passed to the source directly, varies by source

  --- NOTE: All of these options may be functions to get dynamic behavior
  --- See the type definitions for more information
  enabled = true, -- Whether or not to enable the provider
  async = false, -- Whether we should show the completions before this provider returns, without waiting for it
  timeout_ms = 2000, -- How long to wait for the provider to return before showing completions and treating it as asynchronous
  transform_items = nil, -- Function to transform the items before they're returned
  should_show_items = true, -- Whether or not to show the items
  max_items = nil, -- Maximum number of items to display in the menu
  min_keyword_length = 0, -- Minimum number of characters in the keyword to trigger the provider
  -- If this provider returns 0 items, it will fallback to these providers.
  -- If multiple providers fallback to the same provider, all of the providers must return 0 items for it to fallback
  fallbacks = {},
  score_offset = 0, -- Boost/penalize the score of the items
  override = nil, -- Override the source's functions
}
```

### Show Buffer completions with LSP

By default, the buffer source will only show when the LSP source is disabled or returns no items. You may always show the buffer source via:

```lua
sources = {
  providers = {
    -- defaults to `{ 'buffer' }`
    lsp = { fallbacks = {} }
  }
}
```

## Terminal and Cmdline Sources

::: info
Terminal completions are 0.11+ only! Known bugs in v0.10. Cmdline completions are supported on all versions
:::

You may use `cmdline` and `term` sources via the `cmdline.sources` and `term.sources` tables. You may see the defaults in the [reference](./reference.md#mode-specific). There's no source for shell completions at the moment, [contributions welcome](https://github.com/Saghen/blink.cmp/issues/1149)!

## Using `nvim-cmp` sources

Blink can use `nvim-cmp` sources through a compatibility layer developed by [stefanboca](https://github.com/stefanboca): [blink.compat](https://github.com/Saghen/blink.compat). Please open any issues with `blink.compat` in that repo

## Checking status of sources providers

The command `:BlinkCmp status` can be used to view which sources providers are enabled or not enabled.

## Community sources

::: info
See [blink.compat](https://github.com/saghen/blink.compat) for using `nvim-cmp` sources
:::

Here is a non-exhaustive list of third-party plugins providing additional completion sources. Please open a PR to add yours.

- [blink-cmp-agda-symbols](https://github.com/4e554c4c/blink-cmp-agda-symbols) by `4e554c4c`: [Agda](https://wiki.portal.chalmers.se/agda/pmwiki.php) symbols
- [blink-cmp-avante](https://github.com/Kaiser-Yang/blink-cmp-avante) by `Kaiser-Yang`: [Avante](https://github.com/yetone/avante.nvim)
- [blink-cmp-conventional-commits](https://github.com/disrupted/blink-cmp-conventional-commits) by `disrupted`: Git [conventional commits](https://www.conventionalcommits.org)
- [blink-cmp-copilot-chat](https://github.com/pxwg/blink-cmp-copilot-chat) by `pxwg`: [CopilotChat.nvim](https://github.com/CopilotC-Nvim/CopilotChat.nvim)
- [blink-cmp-copilot](https://github.com/giuxtaposition/blink-cmp-copilot) by `giuxtaposition`: Github Copilot
- [blink-cmp-ctags](https://github.com/netmute/blink-cmp-ctags) by `netmute`: Ctags
- [blink-cmp-dap](https://github.com/mayromr/blink-cmp-dap) by `mayromr`: DAP repl
- [blink-cmp-dat-word](https://github.com/xieyonn/blink-cmp-dat-word) by `xieyonn`: Word
- [blink-cmp-dictionary](https://github.com/Kaiser-Yang/blink-cmp-dictionary) by `Kaiser-Yang`: Word
- [blink-cmp-env](https://github.com/bydlw98/blink-cmp-env) by `bydlw98`: Environment variables
- [blink-cmp-emoji](https://github.com/timrydefalk/blink-cmp-emoji) by `timrydefalk`: Unicode Emoji v17.0 glyphs sans Zero Width Joiner
- [blink-cmp-ghostty](https://github.com/barrettruth/blink-cmp-ghostty) by `barrettruth`: [Ghostty](https://ghostty.org/) terminal
- [blink-cmp-git](https://github.com/Kaiser-Yang/blink-cmp-git) by `Kaiser-Yang`: Git commits
- [blink-cmp-im](https://github.com/yehuohan/blink-cmp-im) by `yehuohan`: Input Method
- [blink-cmp-kitty](https://github.com/garyhurtz/blink_cmp_kitty) by `garyhurtz`: [Kitty](https://sw.kovidgoyal.net/kitty) terminal
- [blink-cmp-latex](https://github.com/erooke/blink-cmp-latex) by `erooke`: Unicode symbols via latex macros
- [blink-cmp-luasnip-choice](https://github.com/becknik/blink-cmp-luasnip-choice) by `becknik`: [LuaSnip](https://github.com/L3MON4D3/LuaSnip) choice node
- [blink-cmp-nerdfont](https://github.com/timrydefalk/blink-cmp-nerdfont) by `timrydefalk`: Nerdfont glyphs
- [blink-cmp-npm](https://github.com/alexandre-abrioux/blink-cmp-npm.nvim) by `alexandre-abrioux`: NPM package names and versions
- [blink-cmp-register](https://github.com/phanen/blink-cmp-register) by `phanen`: Registers
- [blink-cmp-rg](https://github.com/niuiic/blink-cmp-rg.nvim) by `niuiic`: Ripgrep
- [blink-cmp-spell](https://github.com/ribru17/blink-cmp-spell.git) by `ribru17`: Spell (based on Neovim's spellsuggest)
- [blink-cmp-sshconfig](https://github.com/bydlw98/blink-cmp-sshconfig) by `bydlw98`: SSH config files
- [blink-cmp-supermaven](https://github.com/Huijiro/blink-cmp-supermaven) by `Huijiro`: [supermaven-nvim](https://github.com/supermaven-inc/supermaven-nvim)
- [blink-cmp-tmux](https://github.com/barrettruth/blink-cmp-tmux) by `barrettruth`: [Tmux](https://github.com/tmux/tmux)
- [blink-cmp-tmux](https://github.com/mgalliou/blink-cmp-tmux) by `mgalliou`: [Tmux](https://github.com/tmux/tmux)
- [blink-cmp-zellij](https://github.com/dynamotn/blink-cmp-zellij) by `dynamotn`: [Zellij](https://github.com/zellij-org/zellij)
- [blink-cmp-vsnip](https://codeberg.org/FelipeLema/blink-cmp-vsnip) by `FelipeLema`: [vim-vsnip](https://github.com/hrsh7th/vim-vsnip)
- [blink-cmp-wezterm](https://github.com/junkblocker/blink-cmp-wezterm) by `junkblocker`: [WezTerm](https://wezterm.org) terminal
- [blink-cmp-words](https://github.com/archie-judd/blink-cmp-words) by `archie-judd`: Words and synonyms
- [blink-cmp-yanky](https://github.com/marcoSven/blink-cmp-yanky) by `marcoSven`: [yanky.nvim](https://github.com/gbprod/yanky.nvim)
- [blink-copilot](https://github.com/fang2hou/blink-copilot) by `fang2hou`: Github Copilot
- [blink-emoji.nvim](https://github.com/moyiz/blink-emoji.nvim) by `moyiz`: Emojis
- [blink-nerdfont.nvim](https://github.com/MahanRahmati/blink-nerdfont.nvim) by `MahanRahmati`: [Nerd Fonts](https://www.nerdfonts.com)
- [blink-ripgrep](https://github.com/mikavilpas/blink-ripgrep.nvim) by `mikavilpas`: Ripgrep
- [chezmoi-template.nvim](https://github.com/dpezto/chezmoi-template.nvim) by `dpezto`: [chezmoi](https://chezmoi.io) template data, functions and block snippets
- [cmp-pandoc-references](https://github.com/jmbuhr/cmp-pandoc-references) by `jmbuhr`: Bibliography, reference and cross-ref items
- [cmp-wezterm](https://github.com/delphinus/cmp-wezterm) by `delphinus`: [WezTerm](https://wezterm.org) terminal (also works with `nvim-cmp`)
- [css-vars.nvim](https://github.com/jdrupal-dev/css-vars.nvim) by `jdrupal-dev`: CSS variables
- [ecolog.nvim](https://github.com/ph1losof/ecolog.nvim) by `ph1losof`: Environment variables
- [gitmoji.nvim](https://github.com/Dynge/gitmoji.nvim) by `Dynge`: [gitmojis](https://gitmoji.dev)
- [lazydev](https://github.com/folke/lazydev.nvim) by `folke`: [LuaLS](https://luals.github.io)
- [minuet-ai.nvim](https://github.com/milanglacier/minuet-ai.nvim) by `milanglacier`: AI
- [vim-dadbod-completion](https://github.com/kristijanhusak/vim-dadbod-completion) by `kristijanhusak`: [vim-dadbod](https://github.com/tpope/vim-dadbod)
- [hex-cmp](https://github.com/dbernheisel/hex-cmp) by `dbernheisel`: [Hex.pm](https://hex.pm) package completion for Elixir `mix.exs` files.