Combobox

Text input with a filtered dropdown of suggestions (React Aria ComboBox).

Import

import { ComboBox, ComboBoxItem } from '@marbleui/ui'

Props

<ComboBox>

Prop	Type	Default
children *required	`ReactNode`	`—`
description	`ReactNode`	`—`
errorMessage	`string \| ((validation: ValidationResult) => string)`	`—`
label	`ReactNode`	`—`
placeholder	`string`	`—`
prefix	`ReactNode`	`—`
variant	`FieldVariant`	`—`

Also accepts React Aria props (113).

<ComboBoxItem>

No props of its own.

Also accepts React Aria props (101).

Accessibility

Keyboard interaction, focus management and ARIA semantics come from the underlying primitives: React Aria Button · React Aria ComboBox · React Aria Group · React Aria Input. Follow the primitive's docs for the full keyboard map.

Usage notes

Text input with a filtered list of suggestions. Use it when the list is long or users know what they’re looking for.

<ComboBox label="Assignee" placeholder="Search people">
  {people.map((p) => <ComboBoxItem key={p.id} id={p.id}>{p.name}</ComboBoxItem>)}
</ComboBox>

Filtering is built in (contains, locale-aware). For async results, control items and inputValue and fetch on change.
allowsCustomValue keeps free text that doesn’t match an item.
For multi-select tokens use MultiSelect or TagsInput.

Example source · show

import { ComboBox, ComboBoxItem } from './combobox'

const timezones = [
  'Pacific/Honolulu', 'America/Los_Angeles', 'America/Denver', 'America/Chicago', 'America/New_York',
  'America/Sao_Paulo', 'Europe/London', 'Europe/Amsterdam', 'Europe/Berlin', 'Africa/Cairo',
  'Asia/Dubai', 'Asia/Kolkata', 'Asia/Singapore', 'Asia/Tokyo', 'Australia/Sydney',
].map((id) => ({ id, name: id.split('/')[1]!.replace('_', ' ') }))

const people = [
  { id: 1, name: 'Ada Lovelace', email: 'ada@acme.com' },
  { id: 2, name: 'Grace Hopper', email: 'grace@acme.com' },
  { id: 3, name: 'Alan Turing', email: 'alan@acme.com' },
  { id: 4, name: 'Katherine Johnson', email: 'katherine@acme.com' },
]

export const styles = {
  Outline: () => (
    <ComboBox className="w-64" label="Timezone" placeholder="Search timezones" items={timezones}>
      {(tz) => <ComboBoxItem id={tz.id}>{tz.name}</ComboBoxItem>}
    </ComboBox>
  ),
  Filled: () => (
    <ComboBox className="w-72" variant="filled" label="Assignee" placeholder="Search people" items={people}>
      {(p) => (
        <ComboBoxItem id={p.id} textValue={p.name}>
          <span className="grid size-5 place-items-center rounded-full bg-accent-soft text-[10px] font-medium text-accent-soft-fg">
            {p.name.split(' ').map((n) => n[0]).join('')}
          </span>
          <span className="truncate">{p.name}</span>
          <span className="truncate text-xs text-fg-subtle">{p.email}</span>
        </ComboBoxItem>
      )}
    </ComboBox>
  ),
}

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

Catalog

Category: selection
Priority: Foundation
Primitive: react-aria
React Aria: ComboBox
Base UI: Combobox