Autocomplete

Search field that filters an always-visible list in place (React Aria Autocomplete). Arrow keys move through results while typing.

Import

import { Autocomplete, AutocompleteItem } from '@marbleui/ui'

Props

<Autocomplete>

Prop	Type	Default	Description
children *required	`ReactNode`	`—`
className	`string`	`—`
emptyText	`string`	`'No results'`
items	`Iterable<T>`	`—`
label	`string`	`—`
placeholder	`string`	`'Search…'`
variant	`'card' \| 'plain'`	`'card'`	"card": bordered panel. "plain": no chrome (e.g. inside a popover or dialog).

Also accepts React Aria props (6).

<AutocompleteItem>

No props of its own.

Also accepts React Aria props (100).

Accessibility

Keyboard interaction, focus management and ARIA semantics come from the underlying primitives: React Aria Autocomplete · React Aria Menu · React Aria MenuItem. Follow the primitive's docs for the full keyboard map.

Usage notes

A search field that filters an always-visible list in place, for command-style pickers inside a card, popover or dialog. For a form field with a popover list use ComboBox; for a standalone search input use SearchField.

<Autocomplete placeholder="Search frameworks" items={frameworks}>
  {(f) => <AutocompleteItem id={f.id}>{f.name}</AutocompleteItem>}
</Autocomplete>

Filtering is a case-insensitive “contains” match on each item’s text. When children are not plain strings, set textValue on AutocompleteItem.
Typing keeps focus in the search field while arrow keys move through results. emptyText replaces “No results”.
Items are menu items: handle a pick with onAction on AutocompleteItem. There is no selected-value state.
label (or placeholder) becomes the search field’s aria-label. variant is card or plain.

Example source · show

import { Autocomplete, AutocompleteItem } from './autocomplete'

const frameworks = ['Astro', 'Angular', 'Next.js', 'Nuxt', 'Qwik', 'Remix', 'Solid', 'SvelteKit', 'TanStack Start', 'Vue'].map((name) => ({ id: name, name }))
const people = [
  { id: 'maya', name: 'Maya Chen', role: 'Design' },
  { id: 'charles', name: 'Charles Webb', role: 'Engineering' },
  { id: 'ada', name: 'Ada Lovelace', role: 'Research' },
  { id: 'grace', name: 'Grace Hopper', role: 'Engineering' },
]

export const styles = {
  Card: () => (
    <Autocomplete className="w-72" placeholder="Search frameworks" items={frameworks}>
      {(f) => <AutocompleteItem id={f.id}>{f.name}</AutocompleteItem>}
    </Autocomplete>
  ),
  People: () => (
    <Autocomplete className="w-80" placeholder="Assign to…" items={people}>
      {(p) => (
        <AutocompleteItem id={p.id} textValue={p.name}>
          <span className="grid size-6 place-items-center rounded-full bg-accent-soft text-[10px] font-semibold text-accent-soft-fg">
            {p.name.split(' ').map((n) => n[0]).join('')}
          </span>
          <span className="flex-1">{p.name}</span>
          <span className="text-xs text-fg-subtle">{p.role}</span>
        </AutocompleteItem>
      )}
    </Autocomplete>
  ),
}

Source: packages/ui/src/autocomplete/autocomplete.tsx

Catalog

Category: selection
Priority: Core
Primitive: react-aria
React Aria: Autocomplete
Base UI: Autocomplete