# Combobox

A styled single-select input that searches its options as the user types. Wraps the headless `Combobox` primitive; the popup portals and positions itself.

## Use for

- picking one option from a long list by typing to search
- a country or language picker
- a search list inside another popup, with `inline` and `Combobox.List`

## Practices

- Do: Pass `items` and `itemToStringLabel` to `Combobox.Root` and render options with `Combobox.Collection`, so the search filters them.
- Do: Keep `Combobox.Empty` mounted, so screen readers announce it when nothing matches.
- Do: Wrap the input and its buttons in `Combobox.InputGroup`, so the popup lines up with the whole group.
- Do: Pass `defaultInputValue` when an initial selection's label differs from its value.
- Do: Give `Combobox.Input` and `Combobox.Trigger` a localized accessible name, and `Combobox.Clear` a localized `aria-label`.

## API reference

### Combobox.Root

Holds the open state, the search text and the selected value. Clearing the input selects `null`. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly Item[]` |  | Every option's item. `Collection` renders those that match the search. |
| `itemToStringLabel` | `(item: Item) => string` |  | The label an item is searched by. |
| `value` | `string \| null` |  | The selected value, when controlled. |
| `defaultValue` | `string \| null` | `null` | The selected value on mount. |
| `onValueChange` | `(value: string \| null) => void` |  | Called with the new value, or `null` when cleared. |
| `inputValue` | `string` |  | The search text, when controlled. |
| `defaultInputValue` | `string` | `''` | The search text on mount. |
| `onInputValueChange` | `(value: string) => void` |  | Called with the new search text. |
| `open` | `boolean` |  | Whether the popup is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the popup is open on mount. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the popup opens or closes. |
| `placement` | `'top' \| 'right' \| 'bottom' \| 'left' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Popup placement. |
| `sideOffset` | `number` | `8` | Gap between the anchor and the popup, in px. |
| `inline` | `boolean` |  | Search inside another surface. Bind `open` to that surface and use `Combobox.List`. |
| `openOnInputClick` | `boolean` | `true` | Opens the popup when the input is clicked. No effect with `inline`. |

### Combobox.Collection

Renders the root's `items` that match the search text, case-insensitively. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(item: Item) => ReactNode` |  | Renders one item. Annotate the parameter with the item type. |

### Combobox.InputGroup

An `InputGroup.Root` around the input and its buttons. The popup anchors to it, and pressing inside it keeps the popup open.

### Combobox.Input

The search `input`, rendered as `Input`. Inside an input group it is `ghost` and takes the group size.

Slot: `cl-combobox-input`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `ComboboxSize` | `'md'` | `sm`, `md` or `lg`. Ignored inside an input group. |
| `variant` | `InputVariant` | `` `ghost` in an input group, else `default` `` | The `Input` variant. |

### Combobox.Trigger

A `Button` that toggles the popup. Shows a chevron when given no children.

Slot: `cl-combobox-trigger`

### Combobox.Clear

A `Button` that clears the search and the selection. Out of the tab order, with the default `aria-label` 'Clear'. Shows an X when given no children.

Slot: `cl-combobox-clear`

### Combobox.Popup

The floating, scrollable listbox. Portals and positions itself; the positioner carries `cl-combobox-positioner` and the scroll box `cl-combobox-viewport`.

Slot: `cl-combobox-popup`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `anchor` | `React.ComponentPropsWithoutRef<typeof HeadlessCombobox.Positioner>['anchor']` |  | Positions the popup against this instead of the input group or input. |
| `portalRoot` | `React.ComponentPropsWithoutRef<typeof HeadlessCombobox.Portal>['root']` | `` `document.body` `` | Where the popup portals. |

### Combobox.List

A scrollable listbox in flow, for a combobox embedded in another surface. Turns on inline mode.

Slot: `cl-combobox-list`

### Combobox.Option

One option.

Slot: `cl-combobox-option`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The value selected when the option is chosen. |
| `label` | `string` | `` `value` `` | The text typeahead matches. |
| `disabled` | `boolean` |  | Makes the option unselectable. |

### Combobox.Media

A square leading column for an icon, flag or avatar, as a `span`.

Slot: `cl-combobox-option-media`

### Combobox.Label

The option's name, as a `span`. Truncates to one line.

Slot: `cl-combobox-option-label`

### Combobox.Detail

Secondary trailing text, such as a code or count. Stays whole while the label truncates.

Slot: `cl-combobox-option-detail`

### Combobox.OptionIndicator

Shows on the selected option. A checkmark when given no children.

Slot: `cl-combobox-option-indicator`

### Combobox.Empty

A polite `role="status"` region that shows its children only when nothing matches.

Slot: `cl-combobox-empty`

## Examples

### A searchable picker

```tsx
<Combobox.Root items={countries} itemToStringLabel={country => country.name}>
  <Combobox.InputGroup>
    <Combobox.Input aria-label={m.country} />
    <Combobox.Trigger aria-label={m.showCountries} />
  </Combobox.InputGroup>
  <Combobox.Popup>
    <Combobox.Empty>{m.noResults}</Combobox.Empty>
    <Combobox.Collection>
      {(country: Country) => (
        <Combobox.Option key={country.code} value={country.code} label={country.name}>
          <Combobox.Label>{country.name}</Combobox.Label>
          <Combobox.OptionIndicator />
        </Combobox.Option>
      )}
    </Combobox.Collection>
  </Combobox.Popup>
</Combobox.Root>
```

## Related

- [InputGroup](/docs/components/input-group.md)
- [Input](/docs/components/input.md)
- [Menu](/docs/components/menu.md)
