Autocomplete

import { Autocomplete } from "@nyte-ai/ui/autocomplete";

An input that filters a list of items against what the user types. The input accepts free-form text, so the suggestions only optionally complete it. No Nyte styling here.

Usage

• Pass the data to items on the root and render each entry from a function child on Autocomplete.List. Inside a group, render the group's entries with Autocomplete.Collection.
• Each Autocomplete.Item takes a value identifying it. Pass the item being rendered so props like itemToStringValue receive it.
• mode decides how filtering and inline completion work. "list" filters items and leaves the input alone. "both" filters and completes the input from the highlighted item. "inline" completes without filtering. "none" does neither.
• filter replaces the matching function. filteredItems hands filtering to you entirely, and Autocomplete.useFilter() gives you the default Intl.Collator matcher to build on.
• limit caps the number of items rendered. Tell the reader what was cut with Autocomplete.Status.
• autoHighlight highlights the first match as the user types. Set it to "always" when the list is rendered inline, so a highlight is always present.
• inline on the root renders the list without the popup. Pass open unconditionally alongside it.
• grid on the root moves the highlight across rows and columns. Wrap each row in Autocomplete.Row.
• Keep Autocomplete.Status and Autocomplete.Empty mounted. Their content is announced politely, so update or conditionally render their children instead of hiding the element.
• virtualized tells the list that you render the items yourself with a virtualizer such as @tanstack/react-virtual.

Anatomy

<Autocomplete.Root>
  <Autocomplete.InputGroup>
    <Autocomplete.Input />
    <Autocomplete.Trigger />
    <Autocomplete.Icon />
    <Autocomplete.Clear />
    <Autocomplete.Value />
  </Autocomplete.InputGroup>

  <Autocomplete.Portal>
    <Autocomplete.Backdrop />
    <Autocomplete.Positioner>
      <Autocomplete.Popup>
        <Autocomplete.Arrow />

        <Autocomplete.Status />
        <Autocomplete.Empty />

        <Autocomplete.List>
          <Autocomplete.Row>
            <Autocomplete.Item />
          </Autocomplete.Row>

          <Autocomplete.Separator />

          <Autocomplete.Group>
            <Autocomplete.GroupLabel />
            <Autocomplete.Collection />
          </Autocomplete.Group>
        </Autocomplete.List>
      </Autocomplete.Popup>
    </Autocomplete.Positioner>
  </Autocomplete.Portal>
</Autocomplete.Root>

Examples

<Autocomplete.Root items={models}>
  <Autocomplete.InputGroup>
    <Autocomplete.Input placeholder="Search models" aria-label="Search models" />
    <Autocomplete.Clear aria-label="Clear">
      <IconCrossSmall size={12} />
    </Autocomplete.Clear>
  </Autocomplete.InputGroup>
  <Autocomplete.Portal>
    <Autocomplete.Positioner sideOffset={4}>
      <Autocomplete.Popup>
        <Autocomplete.Empty>No models match</Autocomplete.Empty>
        <Autocomplete.List>
          {(model: string) => (
            <Autocomplete.Item key={model} value={model}>
              {model}
            </Autocomplete.Item>
          )}
        </Autocomplete.List>
      </Autocomplete.Popup>
    </Autocomplete.Positioner>
  </Autocomplete.Portal>
</Autocomplete.Root>

Group the items by nesting them in objects that carry an items array. Autocomplete.Group takes the group's entries and Autocomplete.Collection renders them, so filtering still applies.

const groups = [
  { label: "Anthropic", items: ["claude-opus-4-6", "claude-sonnet-4-6"] },
  { label: "Google", items: ["gemini-3-pro"] },
];

<Autocomplete.Root items={groups}>
  {/* Input group as above */}
  <Autocomplete.Portal>
    <Autocomplete.Positioner sideOffset={4}>
      <Autocomplete.Popup>
        <Autocomplete.List>
          {(group: { label: string; items: string[] }) => (
            <Autocomplete.Group key={group.label} items={group.items}>
              <Autocomplete.GroupLabel>{group.label}</Autocomplete.GroupLabel>
              <Autocomplete.Collection>
                {(model: string) => (
                  <Autocomplete.Item key={model} value={model}>
                    {model}
                  </Autocomplete.Item>
                )}
              </Autocomplete.Collection>
            </Autocomplete.Group>
          )}
        </Autocomplete.List>
      </Autocomplete.Popup>
    </Autocomplete.Positioner>
  </Autocomplete.Portal>
</Autocomplete.Root>;

value with onValueChange controls the input text.

const [query, setQuery] = useState("");

<Autocomplete.Root items={models} value={query} onValueChange={setQuery}>
  {/* Input group and popup as above */}
</Autocomplete.Root>;

Props

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

Root

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

Root Props:

InputGroup

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

InputGroup Props:

InputGroup Data Attributes:

Input

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

Input Props:

Input Data Attributes:

Trigger

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

Trigger Props:

Trigger Data Attributes:

Icon

An icon that indicates that the trigger button opens the popup. Renders a <span> element.

Icon Props:

Clear

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

Clear Props:

Clear Data Attributes:

Value

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

Value Props:

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div> element.

Portal Props:

Backdrop

An overlay displayed beneath the popup. Renders a <div> element.

Backdrop Props:

Backdrop Data Attributes:

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:

Arrow

Displays an element positioned against the anchor. Renders a <div> element.

Arrow Props:

Arrow Data Attributes:

List

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

List Props:

Item

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

Item Props:

Item Data Attributes:

Row

Displays a single row of items in a grid list. Enable grid on the root component to turn the listbox into a grid. Renders a <div> element.

Row Props:

Collection

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:

Group

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

Group Props:

Group Data Attributes:

GroupLabel

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

GroupLabel Props:

Separator

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

Separator Props:

Empty

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:

Status

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:

useFilter

Matches items against a query using Intl.Collator for robust string matching.

Parameters:

Return Value:

type ReturnValue = AutocompleteFilter;

useFilteredItems

Returns the internally filtered items. Treat the result as read-only: it is internal state and may be a shared frozen array.

Return Value:

type ReturnValue = T[];

Additional Types

Accessibility

• Name the input with a <label> element or an aria-label.
• Autocomplete.Input renders role="combobox", Autocomplete.List renders role="listbox", and each Autocomplete.Item renders role="option".
• Arrow Down and Up move the highlight through the items. loopFocus wraps at the ends. Escape closes the popup.
• mode sets aria-autocomplete on the input to list, both, inline, or none.
• Autocomplete.Status and Autocomplete.Empty announce their content politely, which covers async loading and empty results.
• Items expose data-highlighted and data-disabled for styling those states.
• Autocomplete.GroupLabel is associated with its parent group.