Autocomplete

A text input with a list of suggested values. The input stays free-form; picking a suggestion fills the text. Use Combobox instead if the chosen item should be remembered and the value cannot be custom. The input has no border and rests on the color wash unless inline, which also keeps the list in place. Hover and focus only shift lightness. A highlighted row shows the accent dot. Empty, status, and group labels are Light.

Search tags

Anatomy

<UiAutocompleteRoot :items="items">
  <UiAutocompleteInputGroup>
    <UiAutocompleteIcon />
    <UiAutocompleteInput />
    <UiAutocompleteClear />
    <UiAutocompleteTrigger />
    <UiAutocompleteValue />
  </UiAutocompleteInputGroup>
  <UiAutocompletePortal>
    <UiAutocompletePositioner>
      <UiAutocompletePopup>
        <UiAutocompleteStatus />
        <UiAutocompleteEmpty>No matches.</UiAutocompleteEmpty>
        <UiAutocompleteList v-slot="{ items }">
          <UiAutocompleteGroup v-for="group in items" :key="group.value" :items="group.items">
            <UiAutocompleteGroupLabel>{{ group.value }}</UiAutocompleteGroupLabel>
            <UiAutocompleteCollection v-slot="{ items: groupItems }">
              <UiAutocompleteRow>
                <UiAutocompleteItem v-for="item in groupItems" :key="item.id" :value="item" />
              </UiAutocompleteRow>
            </UiAutocompleteCollection>
          </UiAutocompleteGroup>
        </UiAutocompleteList>
      </UiAutocompletePopup>
    </UiAutocompletePositioner>
  </UiAutocompletePortal>
</UiAutocompleteRoot>

Item values

Pass the item itself as value on each UiAutocompleteItem. itemToStringValue (or label / value / title on the object) is used for the input text and the default filter.

Examples

Async search

Drive items yourself (filter null) and put loading, error, or result counts in UiAutocompleteStatus. Hide the portal until there is a status.

Search movies by name or year

Inline autocomplete

mode="both" filters the list and temporarily fills the input with the highlighted item (the rest of the match is selected). mode also accepts list (default), inline, and none.

Search tags

Grouped

Pass groups as { value, items }[]. Render UiAutocompleteGroup, GroupLabel, and Collection inside the list.

Select a tag

Fuzzy matching

Replace the default includes filter with a filter function so typos and scattered characters still match.

Fuzzy search documentation

Limit results

limit caps visible rows. Root’s slot exposes hiddenCount for UiAutocompleteStatus.

Limit results to 8

Auto highlight

autoHighlight highlights the first match after the user types. Use "always" when the list is shown inline (for example inside a dialog).

Auto highlight on type

Command palette

inline plus a controlled open list inside a Dialog. Items run an action on click instead of only filling the field.

Grid layout

grid lets arrow keys move across UiAutocompleteRow cells. This demo inserts the emoji into a neighboring text field.

Virtualized

virtualized skips automatic scrollIntoView so a large list can own scrolling. This demo renders 1000 items with native overflow (no extra virtualization library).

Virtualized list

API reference

Root

Groups all parts. Renders a <div>. Default slot also receives { items, query, matchCount, hiddenCount }.

Prop	Type	Default	Description
`items`	`unknown[] \| Group[]`	`[]`	Flat items or groups with an `items` array.
`itemToStringValue`	`(item) => string`	label / value / title	String used for the input and the default filter.
`filter`	`((item, query, itemToString?) => boolean) \| null`	includes	Custom matcher. `null` disables internal filtering.
`defaultValue`	`string`	`''`	Uncontrolled input value.
`value`	`string`	—	Controlled input (`v-model:value`).
`defaultOpen`	`boolean`	`false`	Uncontrolled popup.
`open`	`boolean`	—	Controlled popup (`v-model:open`).
`autoHighlight`	`boolean \| 'always'`	—	Highlight the first match while typing, or always.
`keepHighlight`	`boolean`	—	Keep the highlighted item when the pointer leaves the list.
`highlightItemOnHover`	`boolean`	`true`	Highlight on pointer move.
`loopFocus`	`boolean`	`true`	Arrow keys wrap between the input and the ends of the list.
`limit`	`number`	`-1`	Max visible items. `-1` is unlimited.
`mode`	`'list' \| 'both' \| 'inline' \| 'none'`	`'list'`	Filtering and inline autocompletion.
`inline`	`boolean`	—	Render the list in-place; skip outside-press dismiss.
`grid`	`boolean`	—	Arrow keys move by row/column.
`virtualized`	`boolean`	—	Do not auto-scroll the highlighted item into view.
`openOnInputClick`	`boolean`	—	Open the popup when the input is clicked.
`disabled`	`boolean`	—	Ignore interaction. Sets `data-disabled`.

Emits select with the chosen item and itemHighlighted when the highlight moves.

Attribute	Description
`data-open`	Present when the popup is open.
`data-disabled`	Present when the autocomplete is disabled.
`data-inline`	Present when `inline` is set.

Input

Combobox field. Renders an <input>. Arrow keys move the highlight, Enter selects, Escape closes.

Prop	Type	Default	Description
`placeholder`	`string`	—	Placeholder text.
`id`	`string`	—	Native id.

Attribute	Description
`data-popup-open`	Present when the popup is open.
`data-list-empty`	Present when there are no visible items.
`data-disabled`	Present when disabled.

InputGroup

Lays out the field with icon, clear, and trigger. Registers as the popup anchor.

Attribute	Description
`data-popup-open`	Present when the popup is open.

Trigger

Button that opens and closes the popup. Renders a <button>.

Attribute	Description
`data-popup-open`	Present when the popup is open.
`data-disabled`	Present when disabled.

Clear

Clears the input. Hidden when the value is empty.

Icon

Decorative icon next to the input.

Value

Current input text. Default slot is the string; scoped slot receives { value }.

Portal

Teleports to body while the popup is present.

Prop	Type	Default	Description
`hidden`	`boolean`	—	Skip rendering even while present.

Attribute	Description
`data-open`	Present when the popup is open.
`data-closed`	Present while present but not open.
`data-starting-style`	Present while animating in.
`data-ending-style`	Present while animating out.

Positioner

Pins the popup to the input or trigger with position: fixed. Sets --anchor-width, --available-width, and --available-height.

Prop	Type	Default	Description
`sideOffset`	`number`	`4`	Gap below the anchor.
`align`	`'start' \| 'end'`	`'start'`	Align to the start or end of the anchor.

Popup surface. Enter and leave use data-starting-style / data-ending-style (scale 0.98, 100ms). No animation library. No drop-shadow.

Attribute	Description
`data-open`	Present when open.
`data-closed`	Present when closed.
`data-empty`	Present when the list is empty.
`data-starting-style`	Present while animating in.
`data-ending-style`	Present while animating out.

List

Listbox. Scoped slot exposes the filtered items (flat or grouped).

Attribute	Description
`data-empty`	Present when there are no visible items.

Item

One option. Renders a role="option" element. data-highlighted for the active row.

Group

Section of items. Renders role="group".

Prop	Type	Default	Description
`items`	`unknown[]`	—	Items for `Collection`.

GroupLabel

Heading for a group.

Collection

Passes the current group’s items to its scoped slot.

Row

A grid row (role="row") for grid keyboard movement.

Status

Live region for loading, errors, or “hiding N results”.

Empty

Shown when the filter matches nothing.

Separator

Visual divider inside the popup.