# Combobox

Searchable select that opens a list of options and highlights the letters you type in each one. It forgives typos and initials, shows recent picks before you type, and can add a new option.

> Composed · Pro · Forms & Inputs — React Native, Expo Go incompatible (dev build required).

## Install

```bash
npx @lumioui/cli add pro/combobox
```

## Import

```tsx
import { Combobox } from "@/components/ui/combobox/combobox";
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `ComboboxOption[]` | — |
| `value?` | `string` | Controlled value. Pair with `onValueChange`; omit for uncontrolled. |
| `defaultValue?` | `string` | Uncontrolled initial value. Ignored when `value` is provided. |
| `onValueChange?` | `(value: string) => void` | Selection callback — optional so uncontrolled usage needs no wiring. |
| `open?` | `boolean` | Controlled open state. Pair with `onOpenChange`; omit for uncontrolled. |
| `onOpenChange?` | `(open: boolean) => void` | — |
| `disabled?` | `boolean` | Disables the trigger — dims it and blocks opening the sheet. |
| `placeholder?` | `string` | — |
| `searchPlaceholder?` | `string` | — |
| `title?` | `string` | Optional sheet heading. Rendered only when provided. |
| `recent?` | `string[]` | Values shown under "Recent" before anything is typed. Picks made in  the sheet join the front of this list. |
| `suggested?` | `string[]` | Values shown under "Suggested" before anything is typed. |
| `sectionLabels?` | `{ recent?: string` | Section headings. Defaults "Recent", "Suggested", "All". |
| `suggested?` | `string` | — |
| `all?` | `string }` | — |
| `onQueryChange?` | `(query: string) => void` | Fires as the search text changes — fetch remote options here. |
| `loading?` | `boolean` | Results are on their way: rows on screen hold still and dim; with no  rows yet, dim placeholder rows hold the layout. |
| `filter?` | `boolean` | Fuzzy-filter and rank options locally. Default true; turn off when the  server already filtered — matches are still lit. |
| `onCreate?` | `(query: string) => ComboboxOption | void | Promise<ComboboxOption | void>` | Offer an "Add “…”" row when no option's label equals the query. Return  the new option (or a promise of it) to pick it straight away. |
| `createLabel?` | `(query: string) => string` | Create row label. Default `Add “query”`. |
| `createHint?` | `string` | Second line of the create row, e.g. "New traveller". |
| `emptyText?` | `string` | Line under "No match for …". |
| `emptyAction?` | `ComboboxEmptyAction` | The empty state's action. Default clears the search. |
| `className?` | `string` | — |

## Icons rendered

- `check` — /icons.html?i=check
- `plus` — /icons.html?i=plus
- `search` — /icons.html?i=search
- `chevron-down` — /icons.html?i=chevron-down
- `x` — /icons.html?i=x

Source: https://lumioui.com/components/combobox