# Combobox

Searchable single-select picker. Composes `<Popover>` + `<Command>` + `<Button>` into the canonical shadcn pattern. Use for country / city / airport / category pickers where `<Select>` becomes unwieldy past ~10 options.

[View examples](https://marsam.rahhal.app/components/combobox) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/combobox`

**Category:** `forms`

## Behavior

- Always controlled — pass `value` (string) and `onChange`.
- The dropdown filters as the user types via cmdk. By default the filter runs against the option's `label` (when it's a string) or its `value`. Pass `searchValue` per option to override — useful for bilingual lookups (`"Saudi Arabia السعودية"`).
- Selecting the already-selected option clears the value (returns `undefined` to `onChange`).

## Props

| prop | type | purpose |
| --- | --- | --- |
| value | string | undefined | currently-selected option value |
| onChange | (next | undefined) => void | fires on pick / clear |
| options | ComboboxOption[] | available options (required) |
| placeholder | ReactNode | shown on the trigger when no value |
| searchPlaceholder | string | placeholder inside the search input |
| emptyMessage | ReactNode | shown when filter matches nothing |
| width | string (Tailwind) | applied to trigger and content; default `w-[240px]` |
| disabled | boolean | disables the trigger |

## Patterns

- Always treat `value` as a tag, not a label — the option's `label` is presentational and may include localized text.
- For multi-select, build with `<Command>` + `<Popover>` directly; this single-select wrapper intentionally returns the simpler API.