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

# Autocomplete Wireframe Variables

> Template variables exposed by the Autocomplete wireframe — read them with velt-data, velt-if, and velt-class to drive dynamic content, conditional rendering, and class toggling.

<Note>
  New to wireframes? Start with [UI Customization Concepts](/ui-customization/overview) and the [Template Variables](/ui-customization/template-variables) overview.
</Note>

## Overview

The **Autocomplete** primitive is the @-mention picker rendered inside `<velt-autocomplete-panel>` (or `<velt-autocomplete-tool>`), mounted by composers — most prominently the [Comment Dialog Composer](./comment-dialog/wireframe-variables#comment-dialog-composer). Variables below are available inside any `<velt-autocomplete-...-wireframe>` tag via three forms:

| You want to…              | Use                         | Example                                                                    |
| ------------------------- | --------------------------- | -------------------------------------------------------------------------- |
| Display a value as text   | `<velt-data field="var" />` | `<velt-data field="option.name" />`                                        |
| Hide / show conditionally | `velt-if="{var}"`           | `velt-if="{componentConfig.flattenedItems.length} === 0"`                  |
| Toggle a CSS class        | `velt-class="'cls': {var}"` | `velt-class="'custom-search': {componentConfig.customAutocompleteSearch}"` |

<Note>
  This feature uses the **flat-config** access pattern — top-level state is referenced via the explicit `componentConfig.<path>` form. Iteration variables (`option`, `chip`) are injected by specific subcomponents and resolve as bare names — see [Context-Specific Variables](#context-specific-variables) below.
</Note>

## Component Config

Panel-level state shared with every Autocomplete primitive.

| Variable                                            | Type                                  | Description                                                        | Example                                                                    |
| --------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `componentConfig.flattenedItems`                    | `FlattenedItem[]`                     | Visible options after grouping / filtering.                        | `<velt-data field="componentConfig.flattenedItems.length" />`              |
| `componentConfig.trackByFlattenedItem`              | `Function`                            | Identity function used internally to track virtual-scroll items.   | *Internal — used as a track-by function.*                                  |
| `componentConfig.onOptionClick`                     | `Function`                            | Click handler for a custom option. Wire this up in your wireframe. | *Call this from your custom option markup.*                                |
| `componentConfig.newUserContactError`               | `string` \| `undefined`               | Validation error for the in-progress new-contact entry.            | `velt-if="{componentConfig.newUserContactError}"`                          |
| `componentConfig.newUserContact`                    | `SelectorDataListItem` \| `undefined` | The in-progress new-contact entry.                                 | `<velt-data field="componentConfig.newUserContact.name" />`                |
| `componentConfig.customAutocompleteSearch`          | `boolean`                             | Custom-search mode is active.                                      | `velt-class="'custom-search': {componentConfig.customAutocompleteSearch}"` |
| `componentConfig.variant`                           | `string`                              | Per-instance variant tag.                                          | `<velt-data field="componentConfig.variant" />`                            |
| `componentConfig.contactsWithoutGroup`              | `SelectorDataListItem[]`              | Contacts not assigned to any group.                                | `<velt-data field="componentConfig.contactsWithoutGroup.length" />`        |
| `componentConfig.groups`                            | `GroupData[]`                         | Available mention groups.                                          | `<velt-data field="componentConfig.groups.length" />`                      |
| `componentConfig.expandMentionGroups`               | `boolean`                             | Render group rows as expanded.                                     | `velt-class="'expanded-groups': {componentConfig.expandMentionGroups}"`    |
| `componentConfig.showMentionGroupsFirst`            | `boolean`                             | Show group rows above contact rows.                                | `velt-class="'groups-first': {componentConfig.showMentionGroupsFirst}"`    |
| `componentConfig.showMentionGroupsOnly`             | `boolean`                             | Only show group rows.                                              | `velt-class="'groups-only': {componentConfig.showMentionGroupsOnly}"`      |
| `componentConfig.customGroupsEnabled`               | `boolean`                             | Custom-groups feature is enabled.                                  | `velt-if="{componentConfig.customGroupsEnabled}"`                          |
| `componentConfig.autoCompleteScrollConfig.itemSize` | `number`                              | Virtual-scroll item-size config.                                   | *Internal — virtual-scroll config.*                                        |

## Context-Specific Variables

These are only resolvable inside the nested wireframe tags noted in the **Available in** column. Each is injected by the iteration primitive that owns the tag.

| Variable       | Type                                                 | Available in                                                                                               | Example                                   |
| -------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `option`       | `SelectorDataListItem`                               | `<velt-autocomplete-option-wireframe>`, `<velt-autocomplete-group-option-wireframe>`, and their child tags | `<velt-data field="option.name" />`       |
| `option.user`  | [`User`](/api-reference/sdk/models/data-models#user) | Same as above — when the option represents a user.                                                         | `<velt-data field="option.user.email" />` |
| `option.group` | `GroupData`                                          | Same as above — when the option represents a group.                                                        | `<velt-data field="option.group.name" />` |
| `chip`         | `AutocompleteChipConfig`                             | `<velt-autocomplete-chip-wireframe>` and its tooltip child tags                                            | `<velt-data field="chip.label" />`        |

## Type Reference

Types referenced by the variables above:

| Type                                                                                     | Description                                                                                         |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [`User`](/api-reference/sdk/models/data-models#user)                                     | Identified end-user object (used by `option.user`).                                                 |
| [`FlattenedItem`](/api-reference/sdk/models/data-models#flatteneditem)                   | Visible-option row produced after grouping / flattening.                                            |
| [`SelectorDataListItem`](/api-reference/sdk/models/data-models#selectordatalistitem)     | Selectable item (`option`) — has `name`, `email`, `description`, optional `user`, optional `group`. |
| [`GroupData`](/api-reference/sdk/models/data-models#groupdata)                           | Mention-group object (`name`, `userCount`, members).                                                |
| [`AutocompleteChipConfig`](/api-reference/sdk/models/data-models#autocompletechipconfig) | Inline-chip metadata (`label`, plus tooltip data).                                                  |

## Subcomponents

Each subcomponent below has its own wireframe tag (except where noted).

### `autocomplete-tool`

The trigger button that opens the panel (e.g. the "@" icon button in the composer).

* **Public element:** `<velt-autocomplete-tool>`

| Property      | Value                                                                                                                                                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Wireframe tag | No `<velt-autocomplete-tool-wireframe>` registration. The tool's appearance is controlled via the parent's wireframe (e.g. the [composer-action-button](./comment-dialog/wireframe-variables#comment-dialog-composer)). |

***

### `autocomplete-panel`

The opened menu — the Autocomplete root primitive that hosts every other tag.

* **Public element:** `<velt-autocomplete-panel>`

| Property        | Value                                                                             |
| --------------- | --------------------------------------------------------------------------------- |
| Extra variables | None at the panel level. Iteration descendants receive `option` / `chip` per row. |

***

### `autocomplete-empty`

Empty-state shown when no options match the current query.

* **Wireframe tag:** `<velt-autocomplete-empty-wireframe>`

| Property        | Value                                         |
| --------------- | --------------------------------------------- |
| Extra variables | None.                                         |
| `shouldShow`    | `componentConfig.flattenedItems.length === 0` |

***

### `autocomplete-option`

A single option row. Composes name + description + icon + error-icon child tags.

* **Wireframe tag:** `<velt-autocomplete-option-wireframe>`

| Variable             | Type                                                 | Example                                    |
| -------------------- | ---------------------------------------------------- | ------------------------------------------ |
| `option`             | `SelectorDataListItem`                               | `<velt-data field="option.name" />`        |
| `option.user`        | [`User`](/api-reference/sdk/models/data-models#user) | `<velt-data field="option.user.email" />`  |
| `option.email`       | `string`                                             | `<velt-data field="option.email" />`       |
| `option.description` | `string`                                             | `<velt-data field="option.description" />` |

| Property | Value                                                                            |
| -------- | -------------------------------------------------------------------------------- |
| Children | `*-option-name`, `*-option-description`, `*-option-icon`, `*-option-error-icon`. |

***

### `autocomplete-group-option`

A group-of-users row, used when `customGroupsEnabled` is true or when mention groups are present in the data.

* **Wireframe tag:** `<velt-autocomplete-group-option-wireframe>`

| Variable                 | Type        | Example                                        |
| ------------------------ | ----------- | ---------------------------------------------- |
| `option.group`           | `GroupData` | `<velt-data field="option.group.name" />`      |
| `option.group.userCount` | `number`    | `<velt-data field="option.group.userCount" />` |

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltAutocompleteGroupOptionWireframe veltClass="'group-row': true">
      <div>
        <VeltData field="option.group.name" />
        (<VeltData field="option.group.userCount" /> members)
      </div>
    </VeltAutocompleteGroupOptionWireframe>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-autocomplete-group-option-wireframe>
      <div velt-class="'group-row': true">
        <velt-data field="option.group.name"></velt-data>
        (<velt-data field="option.group.userCount"></velt-data> members)
      </div>
    </velt-autocomplete-group-option-wireframe>
    ```
  </Tab>
</Tabs>

***

### `autocomplete-chip`

The chip rendered inline when the user picks a mention (lives inside the contenteditable composer input).

* **Wireframe tag:** `<velt-autocomplete-chip-wireframe>`

| Variable | Type                     | Example                            |
| -------- | ------------------------ | ---------------------------------- |
| `chip`   | `AutocompleteChipConfig` | `<velt-data field="chip.label" />` |

| Property | Value                                                                                         |
| -------- | --------------------------------------------------------------------------------------------- |
| Children | `*-chip-tooltip`, `*-chip-tooltip-name`, `*-chip-tooltip-description`, `*-chip-tooltip-icon`. |

***

### `autocomplete-panel-search-icon`

The magnifying-glass icon shown in the panel's search input.

* **Wireframe tag:** `<velt-autocomplete-panel-search-icon-wireframe>`

| Property        | Value |
| --------------- | ----- |
| Extra variables | None. |

## Deeply-Nested Wireframe Tags

The option rows and chip tooltips decompose further. Each tag below has its own `<velt-autocomplete-...-wireframe>` registration and inherits context variables from its parent.

### Option child tags

Each tag resolves the parent option's iteration context — `option` (and `option.user` / `option.group` where applicable).

| Tag                                                | Notes                                            | Example                                      |
| -------------------------------------------------- | ------------------------------------------------ | -------------------------------------------- |
| `<velt-autocomplete-option-name-wireframe>`        | Option's display name.                           | `<velt-data field="option.name" />`          |
| `<velt-autocomplete-option-description-wireframe>` | Option's description (typically `option.email`). | `<velt-data field="option.email" />`         |
| `<velt-autocomplete-option-icon-wireframe>`        | Option's avatar / icon.                          | `<velt-data field="option.user.photoUrl" />` |
| `<velt-autocomplete-option-error-icon-wireframe>`  | Error indicator shown for invalid options.       | `velt-if="{option.invalid}"`                 |

### Chip tooltip tags

Each tag resolves the parent chip's `chip` iteration context.

| Tag                                                      | Notes                                | Example                                  |
| -------------------------------------------------------- | ------------------------------------ | ---------------------------------------- |
| `<velt-autocomplete-chip-tooltip-wireframe>`             | Tooltip wrapper shown on chip hover. | (composes the three children below)      |
| `<velt-autocomplete-chip-tooltip-name-wireframe>`        | Tooltip name.                        | `<velt-data field="chip.name" />`        |
| `<velt-autocomplete-chip-tooltip-description-wireframe>` | Tooltip description.                 | `<velt-data field="chip.description" />` |
| `<velt-autocomplete-chip-tooltip-icon-wireframe>`        | Tooltip icon.                        | `<velt-data field="chip.icon" />`        |

## Related

* [Comment Dialog Wireframe Variables](./comment-dialog/wireframe-variables) — the parent composer that mounts the autocomplete panel.
* [Template Variables](/ui-customization/template-variables) — overview of the `velt-data` / `velt-if` / `velt-class` system.