# Combobox

Search a defined collection and commit one option while focus stays in the input.

Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.

## Example

```tsx
"use client";

import { FloodRoot, Field, Combobox } from "@flood-md/react";
import "@flood-md/react/styles.css";

export function Example() {
  return (
    <FloodRoot>
      <Field label="Framework">
        {(control) => <Combobox {...control} name="framework" options={[{value: "react", label: "React"}, {value: "vue", label: "Vue"}, {value: "svelte", label: "Svelte"}]} placeholder="Choose a framework" />}
      </Field>
    </FloodRoot>
  );
}
```

## Design notes

- Typing filters labels and optional keywords; labels remain presentation and only the selected option value is submitted. Enter commits the active option. Escape/Tab/outside interaction discard an uncommitted query. Emptying the input clears selection.
- Native input ref, Field associations, required validity, controlled/uncontrolled value, forms/reset, read-only/disabled and IME editing are preserved. Options need unique nonempty values and labels. Disabled options remain discoverable and cannot be chosen.
- Use clearable for the visible clear action; translate clearLabel/toggleLabel/listLabel/emptyMessage/invalidSelectionMessage. The popup reuses Flood ScrollArea and layer positioning. No arbitrary text, multiple selection, async fetching or virtualization engine is supplied. Available in 0.2.5.
- Only the disclosure chevron is shown by default. Set clearable to opt into the extra clear-selection action; individual MultiSelect tags retain their removal buttons.

## API reference

| Prop | Values | Default |
| --- | --- | --- |
| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
| `invalid` | `boolean` | `—` |
| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
| `options` | `readonly ComboboxOption[]` | `Required` |
| `value` | `string` | `—` |
| `defaultValue` | `string` | `""` |
| `onValueChange` | `(value: string) => void` | `—` |
| `clearable` | `boolean` | `false` |
| `emptyMessage` | `string` | `"No results found."` |
| `listLabel` | `string` | `"Options"` |
| `toggleLabel` | `string` | `"Show options"` |
| `clearLabel` | `string` | `"Clear selection"` |
| `invalidSelectionMessage` | `string` | `"Select an option."` |
| `Native HTML props` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "value" \| "defaultValue" \| "onChange" \| "children">` | `Forwarded` |