> ## 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](/docs/ui-customization/overview) and the [Template Variables](/docs/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`](/docs/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`](/docs/api-reference/sdk/models/data-models#user) | Identified end-user object (used by `option.user`). |
| [`FlattenedItem`](/docs/api-reference/sdk/models/data-models#flatteneditem) | Visible-option row produced after grouping / flattening. |
| [`SelectorDataListItem`](/docs/api-reference/sdk/models/data-models#selectordatalistitem) | Selectable item (`option`) — has `name`, `email`, `description`, optional `user`, optional `group`. |
| [`GroupData`](/docs/api-reference/sdk/models/data-models#groupdata) | Mention-group object (`name`, `userCount`, members). |
| [`AutocompleteChipConfig`](/docs/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`](/docs/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](/docs/ui-customization/template-variables) — overview of the `velt-data` / `velt-if` / `velt-class` system.


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