# Combobox

Headless, unstyled single-select input: typing searches the options and choosing one keeps its value. Focus stays on the input while the arrow keys move a virtual highlight. Given `items`, it filters them by label and shows `Empty` when none match.

## Use for

- the base for a styled select with search
- picking one value from a long list by typing
- a search field inside a popover that picks one value

## Practices

- Don't: Use the primitive in a feature. Use the styled `Combobox` from `src/components/combobox` instead.
- Do: Pass `items` and `itemToStringLabel` on the root, render options through `Combobox.Collection`, and annotate its `children` parameter with the item type.
- Do: Keep `Combobox.Empty` mounted, so screen readers announce the message when it appears.
- Do: Pass a localized `aria-label` to `Combobox.Trigger`, and to `Combobox.Clear`, which defaults to an English `Clear`.
- Do: Pass `defaultInputValue` when an initial selection has a label that differs from its value.
- Do: For search inside another popup, pass `inline`, render `Combobox.List`, and bind `open` to the outer popup.
- Don't: Pass `id` to an option or the list. The primitive owns them to wire the ARIA pairing.

## API reference

### Combobox.Root

Holds the search text, the selected value and the open state. Renders no element. Closing restores the selected label in the input; clearing the input clears the selection.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly Item[]` |  | Every option item. `Collection` renders the ones whose label contains the search text. |
| `itemToStringLabel` | `(item: Item) => string` |  | The label `items` are searched by. Required with `items`. |
| `value` | `string \| null` |  | The selected value, or `null` for none, when controlled. |
| `defaultValue` | `string \| null` | `null` | The selected value on mount, when uncontrolled. |
| `onValueChange` | `(value: string \| null) => void` |  | Called with the selected value, or `null` when cleared. |
| `inputValue` | `string` |  | The search text, when controlled. |
| `defaultInputValue` | `string` | `''` | The search text on mount, when uncontrolled. |
| `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, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `placement` | `Placement` | `'bottom-start'` | Floating UI placement of the positioner. |
| `sideOffset` | `number` | `4` | Gap in px between the anchor and the positioner. |
| `inline` | `boolean` |  | A search input inside another surface. Selecting clears the search instead of showing the label. |
| `openOnInputClick` | `boolean` |  | Opens the popup when the input is clicked. No effect with `inline`. |

### Combobox.Input

An `input` with `aria-autocomplete="list"`. Typing opens the popup and highlights the first option; Enter selects the highlighted one. Carries `data-open` or `data-closed`.

### Combobox.InputGroup

A `div` around the input and its buttons. The popup anchors to it, and a press inside it does not close the popup.

### Combobox.Trigger

A `button`, out of the tab order, that toggles the popup and keeps focus on the input. Carries `aria-expanded`, `aria-haspopup="listbox"`, and `data-open` or `data-closed`.

### Combobox.Clear

A `button`, out of the tab order, that clears the search and selection and focuses the input. Renders only while there is text or a selection.

### Combobox.Portal

Portals its children while the popup is mounted.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| React.RefObject<HTMLElement \| null>` |  | The element to portal into. |

### Combobox.Positioner

The floating `div`, matched to the anchor width and capped at the available height. Carries `data-side`. Closes on Escape or an outside press.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `anchor` | `HTMLElement \| null` | ``the `InputGroup`, then the input`` | The element to position against. |

### Combobox.Popup

Wraps the options with transition attributes. Its children stay frozen while it closes, so the list does not change mid-exit.

### Combobox.List

An inline listbox, used in place of `Positioner` and `Popup` inside another surface. Escape and outside presses pass to that surface.

### Combobox.Collection

Renders the root `items` that match the search. Renders all of them when the input shows the selected label.

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

### Combobox.Option

One `role="option"`. Carries `data-selected`, `data-active` while highlighted, and `data-disabled`. A click selects it and returns focus to the input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The value passed to `onValueChange`. |
| `label` | `string` | `` `value` `` | The text shown in the input once selected. |
| `disabled` | `boolean` |  | Skips the option on Enter and ignores clicks. |

### Combobox.OptionIndicator

An `aria-hidden` `span` that renders only inside the selected option, such as a check mark.

### Combobox.Empty

A polite `role="status"` region that shows its children only when no `items` match. Without `items` on the root it always shows them.

### Combobox.Arrow

An optional `svg` arrow pointing at the anchor, from Floating UI. Carries `data-side`.

## Examples

### Search a list

```tsx
<Combobox.Root items={fruits} itemToStringLabel={fruit => fruit}>
  <Combobox.InputGroup>
    <Combobox.Input aria-label='Fruit' />
    <Combobox.Trigger aria-label='Show fruits' />
  </Combobox.InputGroup>
  <Combobox.Positioner>
    <Combobox.Popup>
      <Combobox.Empty>No fruit found</Combobox.Empty>
      <Combobox.Collection>
        {(fruit: string) => (
          <Combobox.Option key={fruit} value={fruit}>
            {fruit}
            <Combobox.OptionIndicator>✓</Combobox.OptionIndicator>
          </Combobox.Option>
        )}
      </Combobox.Collection>
    </Combobox.Popup>
  </Combobox.Positioner>
</Combobox.Root>
```

## Related

- [Autocomplete](/docs/primitives/autocomplete.md)
- [Select](/docs/components/select.md)
