# ListBox

A named single or multiple selection list with native validation and semantic feedback.

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, ListBox } from "@flood-md/react";
import "@flood-md/react/styles.css";

export function Example() {
  return (
    <FloodRoot>
      <ListBox label="Framework" name="framework" defaultValue="react" options={[{value:"react",label:"React"},{value:"vue",label:"Vue"},{value:"svelte",label:"Svelte"}]} />
    </FloodRoot>
  );
}
```

## Design notes

- Use a scalar value/defaultValue in single mode and an array in multiple mode. onValueChange returns the matching shape. Stable, unique nonempty option IDs are submitted as repeated hidden native form fields when name is supplied. Uncontrolled reset restores the initial selection.
- The list owns one Tab stop and aria-activedescendant. Arrows/Home/End move through enabled options; single selection follows navigation. Space/Enter selects or toggles. Typing searches option-label prefixes. Disabled options cannot be selected; readOnly retains navigation and copying without changing the value.
- Provide a clear label or use hideLabel with the accessible label preserved. Use disabled on the composite to remove its Tab stop. The list is not virtualized and does not fetch options. Available in 0.2.5.
- required validates accepted selection; readonly bypasses validation and disabled excludes form values.
- description/message and status share the field feedback contract. validationMessage is a host-owned blocking constraint.

## API reference

| Prop | Values | Default |
| --- | --- | --- |
| `label` | `string` | `Required` |
| `hideLabel` | `boolean` | `false` |
| `required` | `boolean` | `—` |
| `requiredMessage` | `string` | `—` |
| `validationMessage` | `string` | `—` |
| `description` | `string` | `—` |
| `message` | `string` | `—` |
| `status` | `"error" \| "warning" \| "success" \| "info"` | `—` |
| `invalid` | `boolean` | `—` |
| `options` | `readonly ComboboxOption[]` | `Required` |
| `value` | `string \| readonly string[]` | `—` |
| `defaultValue` | `string \| readonly string[]` | `—` |
| `onValueChange` | `(value: string \| string[]) => void` | `—` |
| `multiple` | `boolean` | `false` |
| `selectionBehavior` | `"automatic" \| "manual"` | `—` |
| `appearance` | `"surface" \| "plain"` | `—` |
| `disabled` | `boolean` | `false` |
| `readOnly` | `boolean` | `false` |
| `name` | `string` | `—` |
| `form` | `string` | `—` |
| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "defaultValue" \| "onChange">` | `Forwarded` |