{
  "title": "Combobox",
  "description": "A searchable Select. Use for long lists or async option loading where typeahead filtering helps users find an option quickly.",
  "url": "/docs/components/combobox",
  "since": null,
  "tags": [],
  "platform": "both",
  "source": "---\ntitle: Combobox\ndescription: A searchable Select. Use for long lists or async option loading where typeahead filtering helps users find an option quickly.\n---\n\nimport { BundleSize } from '@/components/bundle-size';\nimport { Preview } from '@/components/preview';\n\n<BundleSize component=\"Combobox\" />\n\n## When to use\n\n- **Combobox** — long lists (10+ items), typeahead filtering, async option loading.\n- **[Select](/docs/components/select)** — short static lists where clicking is enough.\n\nCombobox is a thin wrapper over Select with `searchable` defaulted to `true`. Every other prop, behavior, and type is identical — see Select's full API reference.\n\n## Basic usage\n\n<Preview name=\"combobox-basic\" />\n\n## Async options\n\nPass an `options` function that returns a promise — Select streams results into the popup as the user types. See [Select → async](/docs/components/select#async).\n\n## API\n\nCombobox accepts every prop of Select. The only difference is the default value of `searchable`.\n\nSee [Select's API reference](/docs/components/select#api) for the full prop list.\n\nBelow is a quick reference of the most commonly used props. Full details live on\nthe Select page.\n\n| Prop | Notes |\n|------|-------|\n| `value` / `defaultValue` | Controlled or uncontrolled selected value. `string` for single, `string[]` for `multiple`. |\n| `onChange` | Fires with the new value on each selection change. |\n| `options` | Static option array. Each item has `value`, `label`, and optional `group` / `disabled`. |\n| `loadOptions` | Async loader for server-backed lists. Returns `{ items, total? }`. |\n| `multiple` | Enables multi-select. Trigger renders a chip per selection. |\n| `disabled` | Disables the control. Forwards `aria-disabled`. |\n| `placeholder` | Trigger label when nothing is selected. |\n| `searchPlaceholder` | Label inside the search input field. |\n| `noOptionsMessage` | Shown when the filter returns zero results. |\n| `loadingMessage` | Shown while an async `loadOptions` call is in flight. |\n| `filterOption` | Custom match predicate `(option, query) => boolean`. |\n| `renderOption` | Custom row renderer `(option, { selected, active }) => ReactNode`. |\n| `dir` | RTL layout — set to `\"rtl\"` for Arabic / Hebrew locales. |\n| `locale` | BCP 47 locale tag. Enables `Intl.Collator` sort when `sortByLocale` is true. |\n| `sortByLocale` | Sort options via `Intl.Collator`. Auto-enabled when `locale` is set. |\n| `virtualized` | Render only the visible option window. Auto-on above 100 items. |\n| `itemHeight` | Fixed row height in px for the virtualization math. Default 36. |\n| `maxMenuHeight` | Popup height in px before scrolling. Default 320. |\n| `maxChips` | Collapse chips to \"N selected\" past this count. Default 3. |\n| `maxSelected` | Cap the number of selected items in multi-select mode. |\n| `pageSize` | Async only — items to fetch per `loadOptions` call. Default 50. |\n| `id` | Forwarded to the trigger for `<label htmlFor>` wiring. |\n| `aria-label` | Accessible label when no visible label is present. |\n| `aria-labelledby` | ID of an external label element. |\n| `aria-describedby` | ID of a description / hint element. |\n| `aria-invalid` | Marks the field invalid. Injected automatically by `<Field>`. |\n| `aria-required` | Marks the field required. Injected automatically by `<Field>`. |\n"
}