Autocomplete

import {
  Autocomplete,
  AutocompleteCollection,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteGroupLabel,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompleteSeparator,
  AutocompleteStatus,
  AutocompleteTrigger,
} from "@nyte-ai/ui/autocomplete";

A search field for a long list, such as fonts or models. For a short list, use Select.

Usage

• Pass the current value as the children of AutocompleteTrigger.
• Pass the data to items on Autocomplete and render each entry from a function child of AutocompleteList. Inside an AutocompleteGroup, render its entries with AutocompleteCollection.
• Give each AutocompleteItem a value. The selected item shows a checkmark.
• value and onValueChange on Autocomplete hold the selection. onValueChange passes null when the selection clears.
• inputValue and onInputValueChange hold the search text.
• To nest the list in another surface, such as a submenu, set inline and open on Autocomplete, drop AutocompleteContent, and set variant="inline".
• Keep AutocompleteStatus and AutocompleteEmpty mounted and change their children, so screen readers announce the change.

Anatomy

<Autocomplete>
  <AutocompleteTrigger />
  <AutocompleteContent>
    <AutocompleteInput />
    <AutocompleteStatus />
    <AutocompleteList>
      <AutocompleteGroup>
        <AutocompleteSeparator />
        <AutocompleteGroupLabel />
        <AutocompleteCollection>
          <AutocompleteItem />
        </AutocompleteCollection>
      </AutocompleteGroup>
    </AutocompleteList>
    <AutocompleteEmpty />
  </AutocompleteContent>
</Autocomplete>

Examples

Searchable picker

interface ModelGroup {
  readonly label: string;
  readonly items: readonly string[];
}

const groups: readonly ModelGroup[] = [
  { label: "Anthropic", items: ["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"] },
  { label: "OpenAI", items: ["gpt-6-luna"] },
  { label: "Google", items: ["gemini-3-pro"] },
];

const [model, setModel] = useState("claude-sonnet-4-6");
const [search, setSearch] = useState("");

<Autocomplete
  items={groups}
  value={model}
  onValueChange={(next) => {
    if (next !== null) setModel(next);
  }}
  inputValue={search}
  onInputValueChange={setSearch}
  autoHighlight
>
  <AutocompleteTrigger aria-label="Model">{model}</AutocompleteTrigger>
  <AutocompleteContent>
    <AutocompleteInput aria-label="Search models" placeholder="Search models" />
    <AutocompleteList>
      {(group: ModelGroup, index: number) => (
        <AutocompleteGroup key={group.label} items={group.items}>
          {index > 0 && <AutocompleteSeparator />}
          <AutocompleteGroupLabel>{group.label}</AutocompleteGroupLabel>
          <AutocompleteCollection>
            {(item: string) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteCollection>
        </AutocompleteGroup>
      )}
    </AutocompleteList>
    <AutocompleteEmpty>No models match</AutocompleteEmpty>
  </AutocompleteContent>
</Autocomplete>;

Inside a submenu

The Menu submenu supplies the popup. filter={null} leaves filtering to you.

<MenuSubContent>
  <Autocomplete
    inline
    open
    filter={null}
    autoHighlight
    items={options}
    value={current}
    onValueChange={(next) => {
      if (next !== null) choose(next);
    }}
    inputValue={search}
    onInputValueChange={setSearch}
  >
    <AutocompleteInput variant="inline" aria-label="Search models" placeholder="Search models" />
    <MenuSeparator />
    <AutocompleteList variant="inline">
      {(option: ModelOption) => (
        <AutocompleteItem variant="inline" key={option.key} value={option}>
          {option.name}
        </AutocompleteItem>
      )}
    </AutocompleteList>
  </Autocomplete>
</MenuSubContent>

Props

Styled parts take xstyle, className, and style; see Theming. Each sets data-slot to its kebab-case name, such as autocomplete-item. Autocomplete, AutocompleteValue, AutocompleteInputGroup, AutocompleteGroup, and AutocompleteCollection pass through Base UI.

The reference tables below come from Base UI, MIT, © Material-UI SAS.

Autocomplete

Groups all parts of the combobox. Doesn't render its own HTML element.

Root Props:

autoComplete Prop References:

• See developer.mozilla.org

AutocompleteTrigger

A button that opens the popup. Renders a <button> element.

Trigger Props:

Trigger Data Attributes:

AutocompleteValue

The current value of the combobox. Doesn't render its own HTML element.

Value Props:

AutocompleteClear

Clears the value when clicked. Renders a <button> element.

Clear Props:

Clear Data Attributes:

AutocompleteContent

Renders the portal, positioner, and popup. The positioning props below go to the positioner. Everything else goes to the popup.

Positioner

Positions the popup against the trigger. Renders a <div> element.

Positioner Props:

alignOffset Prop Example:

<Positioner
  alignOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.width : anchor.height;
  }}
/>

sideOffset Prop Example:

<Positioner
  sideOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.height : anchor.width;
  }}
/>

collisionAvoidance Prop Example:

<Positioner
  collisionAvoidance={{
    side: 'shift',
    align: 'shift',
    fallbackAxisSide: 'none',
  }}
/>

Positioner Data Attributes:

Positioner CSS Variables:

Popup

A container for the list. Renders a <div> element.

Popup Props:

Popup Data Attributes:

AutocompleteInput

A text input to search for items in the list. Renders an <input> element.

Input Props:

Input Data Attributes:

AutocompleteInputGroup

A wrapper for the input and its associated controls. Renders a <div> element.

InputGroup Props:

InputGroup Data Attributes:

AutocompleteList

A list container for the items. Renders a <div> element.

List Props:

AutocompleteItem

An individual item in the list. Renders a <div> element.

Item Props:

Item Data Attributes:

AutocompleteCollection

Renders filtered list items. Doesn't render its own HTML element.

If rendering a flat list, pass a function child to the List component instead, which implicitly wraps it.

Collection Props:

AutocompleteGroup

Groups related items with the corresponding label. Renders a <div> element.

Group Props:

AutocompleteGroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

GroupLabel Props:

AutocompleteSeparator

A visual separator between items or groups. Renders a <div> element.

Separator Props:

Separator Data Attributes:

AutocompleteEmpty

Renders its children only when the list is empty. Requires the items prop on the root component. Announces changes politely to screen readers. This component's root element must remain mounted in the DOM to announce changes consistently across screen readers. Avoid hiding or removing the component itself with display: none, hidden, aria-hidden, or conditional rendering. Prefer updating or conditionally rendering its children instead. Renders a <div> element.

Empty Props:

AutocompleteStatus

Takes up no space while empty.

Displays a status message whose content changes are announced politely to screen readers. Useful for conveying the status of an asynchronously loaded list. This component's root element must remain mounted in the DOM to announce changes consistently across screen readers. Avoid hiding or removing the component itself with display: none, hidden, aria-hidden, or conditional rendering. Prefer updating or conditionally rendering its children instead. Renders a <div> element.

Status Props:

Variant

AutocompleteInput, AutocompleteList, AutocompleteItem, and AutocompleteGroupLabel take variant.

Accessibility

• Name the input and the trigger with aria-label. The trigger's text is only the current value.
• AutocompleteList renders role="listbox" and each AutocompleteItem role="option". The checkmark is hidden from assistive technology.
• Arrow Down and Up move the highlight. The input is part of the loop. Enter picks the highlighted item. Escape closes the popup.
• AutocompleteGroupLabel names its group.
• Keyboard focus on the trigger shows the focus ring.