## Combobox (S—022)

A searchable select with single and multi-select modes, chips, create-new, limits and disabled options.

- URL: https://sundaeui.dev/components/combobox
- Category: Forms & inputs · Art direction: Understated
- Access: Free (no account needed)
- Stack: React 18+, TypeScript, Tailwind CSS; dependencies: none
- Install: `npx shadcn@latest add https://sundaeui.dev/r/combobox.json`
- Tags: tailwind, form, autocomplete, react, input, combobox, multi-select, select

One component for the two most common selection problems. In single mode it is a select you can type into: the current value shows as the placeholder, the list filters by label and hint, and picking an option closes the list. In multiple mode, choices become chips. Backspace on an empty input removes the last one, and an optional max greys out the rest.
Pass onCreate and the list offers “Create ‘…’” for anything that doesn’t exist yet, which suits tags and labels. Disabled options stay visible but can’t be picked, and the list keeps the active option in view while you arrow through it.
Use it instead of a native <select> when there are more than about ten options, or when people know what they want and would rather type it.

### Usage

```tsx
import { Combobox } from '@/components/sundae/combobox'

<Combobox label="Time zone" options={zones} value={tz} onChange={setTz} />

<Combobox
  label="Labels"
  multiple
  max={4}
  options={labels}
  value={selected}
  onChange={setSelected}
  onCreate={(q) => ({ value: slugify(q), label: q })}
/>
```

### Props

- `options` (`ComboOption[]`, required): { value, label, hint?, disabled? }.
- `label` (`string`, required): Visible label.
- `multiple` (`boolean`): Switches value and onChange to string[].
- `value / onChange` (`string | null | string[]`, required): Controlled selection.
- `max` (`number`): Maximum number of selections (multiple only).
- `onCreate` (`(query) => ComboOption | void`): Enables creating options from the query.
- `placeholder / emptyMessage` (`string`): Empty input and no-results text.

### Accessibility

- Follows the ARIA 1.2 combobox pattern: role="combobox", aria-controls, aria-activedescendant and a role="listbox" with aria-selected options.
- Multi-select chips have labelled remove buttons, and Backspace removes the last chip.
- Escape clears the query first, then closes the list.