# combobox

- 分组：组合组件（Composite）
- 页面：/components/combobox
- 源码：packages/react/src/components/combobox.tsx

## 导出

```ts
import { Combobox, useAsyncOptions } from "@modra/react";
```

## Props（ComboboxProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `options` | 是 | `ComboboxOption[]` |  |
| `value` | 否 | `string` |  |
| `defaultValue` | 否 | `string` |  |
| `onValueChange` | 否 | `(value: string) => void` |  |
| `open` | 否 | `boolean` |  |
| `defaultOpen` | 否 | `boolean` |  |
| `onOpenChange` | 否 | `(open: boolean) => void` |  |
| `onSearchChange` | 否 | `(search: string) => void` | Called with the search text. The input itself updates immediately; this callback is debounced by `searchDebounce` and is not fired while an IME composition is in progress. |
| `searchDebounce` | 否 | `number` | Milliseconds to wait before `onSearchChange`. Defaults to 300 when `filter` is `false`, else 0. |
| `filter` | 否 | `boolean \| ComboboxFilter` | `true` (default) filters locally, `false` shows `options` as-is (remote search), or pass a custom filter function. |
| `loading` | 否 | `boolean` | Keeps the previous options on screen and shows an inline indicator while true. |
| `selectedOption` | 否 | `ComboboxOption` | Option shown on the trigger when the selected value is not in the current `options`. |
| `disabled` | 否 | `boolean` |  |
| `placeholder` | 否 | `string` |  |
| `searchPlaceholder` | 否 | `string` |  |
| `emptyText` | 否 | `string` |  |
| `className` | 否 | `string` |  |
| `contentClassName` | 否 | `string` |  |
| `id` | 否 | `string` | Id of the trigger button, so an external `<label htmlFor>` can name it. |
| `invalid` | 否 | `boolean` | Marks the trigger invalid (`aria-invalid`) and applies the destructive border. |
| `onClear` | 否 | `() => void` | When provided, a clear button is shown while a value is selected. It calls this instead of `onValueChange`, so the parent decides what "no selection" means. |
| `error` | 否 | `React.ReactNode` | A load failure to show in the list. Pair with `onRetry`. |
| `onRetry` | 否 | `() => void` | Shows a retry button next to `error`. |