Autocomplete

Base UICopy Anchor Link

Autocomplete combines a text input with a filterable popup. Type to narrow items, pick a row, or keep free-form text when the list is only a suggestion.

Field label, description, error copy, and startAddon / endAddon chrome match Textfield; options render as Autocomplete.Item rows on an elevated Surface like Select. Pass list content as a render function over items, or compose Autocomplete.Group with Autocomplete.Collection for sectioned results. Keep root status mounted and update its children when async messaging changes; clear or omit empty while pending so no-match copy does not flash over a spinner. Fill a form column from a parent Stack with fullWidth / expandChildren — Autocomplete has no fullWidth prop of its own.

AnatomyCopy Anchor Link

Import the component and assemble its parts:

import { Autocomplete } from '@viraui/react';

<Autocomplete>
  <Autocomplete.Item />
  <Autocomplete.Group>
    <Autocomplete.Collection>
      <Autocomplete.Item />
    </Autocomplete.Collection>
  </Autocomplete.Group>
</Autocomplete>

Autocomplete.useFilter and Autocomplete.useFilteredItems stay out of the tree.

When to useCopy Anchor Link

• Large lists where typing to filter is easier than scanning a closed dropdown
• Values that may stay free-form when nothing in the list matches (tags, categories)
• Async search with a mounted status slot while results load

When not to useCopy Anchor Link

• A fixed short list with no typing → Select
• Open text with no suggestion list → Textfield
• A short, always-visible single choice → Radio

RelatedCopy Anchor Link

• Select — closed-choice popup without filtering
• Textfield — single-line text without a suggestion list
• Radio — visible mutually exclusive options

Common examplesCopy Anchor Link

Filterable optionsCopy Anchor Link

A labeled Autocomplete with search chrome and item addons is the baseline suggest pattern. itemToStringValue maps each object to the string written into the input when a row is chosen. When that string matches an item, endAddon can mirror a related preview (here an Avatar).

Buttons inside endAddon must use type="button" so they do not submit a parent form.

Free-form valueCopy Anchor Link

Flat items still allow free-form text — the list suggests options while the input can keep a custom phrase. Prefer this over Select when the value does not have to be one of the options.

Grouped optionsCopy Anchor Link

Grouped items pair with Autocomplete.Group and Autocomplete.Collection so each section keeps its own heading and nested rows.

Async statusCopy Anchor Link

When results load outside the control, set filter={null} and drive items from your fetch. Keep root status mounted — swap Spinner and muted copy inside it while the request runs. Clear or omit empty while pending so the no-match copy does not flash over the spinner.

In iframe previews, shadow roots, or custom overlay hosts, pass container on Autocomplete so the popup portals into that document instead of the default body.

Ask your agentCopy Anchor Link

Add an assignee picker labeled "Assignee" with ten sample names, search-as-you-type filtering, avatar rows, and at most six visible rows in the dropdown.