> ## Documentation Index
> Fetch the complete documentation index at: https://velt-codex-ui-customization-guide-refresh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @Mentions & Autocomplete

> Customize mentions and autocomplete behavior, styling, slots, and related hooks.

The @-mention / autocomplete picker that appears inside comment composers (and the mention chips it produces). You customize **the data** (who/what is mentionable), **the layout** (option rows, groups, empty state), and **the chips**.

## Components

* **Primitive:** `VeltAutocomplete` (+ sub-primitives `VeltAutocompletePanel`, `VeltAutocompleteOption`, `VeltAutocompleteGroupOption`, `VeltAutocompleteEmpty`, `VeltAutocompleteChip`, `VeltAutocompleteChipTooltip`). Most customers don't mount these: autocomplete renders **inside the comment composer**.
* **Wireframes:** `VeltAutocompleteOptionWireframe`, `VeltAutocompleteGroupOptionWireframe`, `VeltAutocompleteEmptyWireframe`, `VeltAutocompleteChipTooltipWireframe`.

## Config props

Customize the data (the most common need): these props live on `<VeltComments>`:

| Prop                                                  | Type                 | What it does                                                                                                                             |
| ----------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `customAutocompleteSearch`                            | **`boolean`**        | **A toggle, not a callback.** Switches the picker to *your* data, which you supply via `ContactElement` / `AutocompleteElement` (below). |
| `expandMentionGroups`                                 | `boolean`            | Expand group members inline                                                                                                              |
| `showMentionGroupsFirst` / `showMentionGroupsOnly`    | `boolean`            | Group ordering / groups-only                                                                                                             |
| `paginatedContactList`                                | `boolean`            | Paginate a long contact list                                                                                                             |
| `atHereEnabled` / `atHereLabel` / `atHereDescription` | `boolean` / `string` | The "@here" option                                                                                                                       |
| `customListDataOnComment`                             | `AutocompleteData`   | Custom (non-contact) mention data                                                                                                        |

<Warning>
  These props do **not** exist: `showMentionGroups`, `customGroups`, `atHere`/`showAtHere`. Use the real names above.
</Warning>

**Supply the contacts/data via hooks (headless config):**

* **Contacts:** `useContactUtils()` → `ContactElement`: `updateContactList(userContacts, config?)`, `updateOrgList(...)`, `enableAtHere()`/`setAtHereLabel()`, `getContactList()`. Read with `useContactList()`.
* **Custom (non-contact) items:** `useAutocompleteUtils()` → `AutocompleteElement.create({ hotkey, type: 'custom'|'contact'|'group', data, groups? })`: combine with `customAutocompleteSearch`.

## CSS: stateful classes

(Override with `!important`, R9b.) Option rows: `velt-autocomplete-option--container`, `--selected`, `--multi-select`; groups: `velt-group-option` (header), `velt-group-member-option`. Chips: `velt-autocomplete--contact-chip`, `--contact-chip-current-user`, `--group-chip`, `.custom-chip`: note **chip classes are styled in a global stylesheet**, so override them globally, not inside a component scope. Empty: `velt-autocomplete-empty--no-results` / `--add-contact` / `--error`.

## Wireframes: slot trees + tokens

```
VeltAutocompleteOptionWireframe → .Icon · .Name · .Description (prop: field) · .ErrorIcon
VeltAutocompleteGroupOptionWireframe        (group header row)
VeltAutocompleteEmptyWireframe              (no-results / add-contact state)
VeltAutocompleteChipTooltipWireframe → .Name · .Description · .Icon
```

`.Description` is the one slot with an input prop (`field`). Read tokens with `{componentConfig.<x>}`: `flattenedItems` (empty when `length === 0`), `groups`, `expandMentionGroups`, `customAutocompleteSearch`; per-row `option` (`.name`/`.email`/`.description`/`.group.name`/`.group.userCount`), `chip` (`.label`).

## Headless hooks

`useContactUtils()` / `useContactList()` / `useContactSelected()`; `useAutocompleteUtils()` / `useAutocompleteChipClick()`.

## Limitations

`customAutocompleteSearch` only flips the mode: you must also feed data. The panel switches to virtual scroll past \~6 items. Some option/group types referenced in tokens are internal shapes (not in the public types): rely on the documented fields above and inspect at runtime if unsure.