> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/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

**Full examples:** [Autocomplete wireframe variables](https://velt.dev/docs/ui-customization/features/async/comments/autocomplete-wireframe-variables.md) has the complete variable reference with tabbed code examples.

| | Primitive | Wireframe |
| - | - | - |
| Autocomplete root | `VeltAutocomplete` | None |
| Option row | `VeltAutocompleteOption` | `VeltAutocompleteOptionWireframe` |
| Group header row | `VeltAutocompleteGroupOption` | `VeltAutocompleteGroupOptionWireframe` |
| Empty state | `VeltAutocompleteEmpty` | `VeltAutocompleteEmptyWireframe` |
| Mention chip | `VeltAutocompleteChip` | None |
| Chip tooltip | `VeltAutocompleteChipTooltip` | `VeltAutocompleteChipTooltipWireframe` |
| Panel | `VeltAutocompletePanel` | None |

> Most customers don't mount the primitives directly: autocomplete renders **inside the comment composer**.

## 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]
>
> Watch out for near-miss names: the real props are `showMentionGroupsFirst` / `showMentionGroupsOnly` (there is no `showMentionGroups`), `atHereEnabled` (there is no `atHere` or `showAtHere`), and `customListDataOnComment` (there is no `customGroups`).

**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` because Velt's own styles are high-specificity; see [CSS](https://velt.dev/docs/ui-customization/styling.md#override-classes).)

| Class | Applies to |
| - | - |
| `velt-autocomplete-option--container`, `--selected`, `--multi-select` | Option rows |
| `velt-group-option` (header), `velt-group-member-option` | Groups |
| `velt-autocomplete--contact-chip`, `--contact-chip-current-user`, `--group-chip`, `.custom-chip` | Chips |
| `velt-autocomplete-empty--no-results` / `--add-contact` / `--error` | Empty state |

> **Chip classes are styled in a global stylesheet**: override them globally, not inside a component scope.

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

| Hook | Purpose |
| - | - |
| `useContactUtils()` | Contact element: update contact/org lists, `@here` config |
| `useContactList()` | Read the current contact list |
| `useContactSelected()` | React to contact selection |
| `useAutocompleteUtils()` | Autocomplete element: create custom mention data |
| `useAutocompleteChipClick()` | React to chip clicks |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.