# Combobox

An input that filters a list as you type, for one value or many.

Tier: Free

## Installation

```bash
npx shadcn add @fetaui/combobox
```

## Usage

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

export function Example() {
  return <Combobox options={people} placeholder="Find a person" onValueChange={setPerson} />
}
```

## API

| Prop | Type | Default |
|---|---|---|
| options | ComboboxOption[] | required |
| multiple | boolean | false |
| value | string or string[] |  |
| defaultValue | string or string[] |  |
| onValueChange | (value) => void |  |
| maxChips | number |  |
| placeholder | string | Search |
| loading | boolean | false |
| onQueryChange | (query) => void |  |
| filter | boolean | true |
| empty | ReactNode | No results |
| invalid | boolean | false |
| disabled | boolean | false |
| animated | boolean | true |

## When to use

- When the list is long enough to need search.
- Multiple suits reviewers and labels.

## When not to use

- For short fixed lists: use Select.

## Accessibility

- Role combobox with aria-expanded and aria-activedescendant.
- The number of matches is announced.
- Chips have named remove buttons.

## Motion

- The list drops from the field in 200 ms.
- The highlight glides between rows.
- Chips pop in, and the rest close the gap.
- With reduced motion, the list appears and chips appear in place.