# Select

Headless, unstyled replacement for a native `<select>`: pick one value, or several with `multiple`, from a fixed list. Has typeahead and arrow-key navigation, and by default lays the selected option over the trigger.

## Use for

- picking one value from a fixed list of options
- picking several values from a fixed list
- a styled dropdown in place of a native select

## Practices

- Do: Pass `label` on each `Select.Option` whose value is not display text. It falls back to `String(value)`.
- Do: Pass `items` when `Select.Value` must show a label before the options mount, such as on first render.
- Do: Put a `Select.GroupLabel` inside every `Select.Group`. It throws outside one.
- Don't: Pass `id` to `Select.Positioner`. The primitive owns it to pair the trigger’s `aria-controls`.
- Don't: Expect `items` to render options. It only resolves labels; render each `Select.Option`.
- Don't: Use it when the user types to filter. Use `Combobox` instead.

## API reference

### Select.Root

Holds the selection, open state and list navigation. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multiple` | `boolean` | `false` | Makes the value an array. Picking toggles an option and keeps the popup open. |
| `value` | `Value \| Value[] \| null` |  | The selection, when controlled. `null` for none, or an array with `multiple`. |
| `defaultValue` | `Value \| Value[] \| null` |  | The selection on mount, when uncontrolled. |
| `onValueChange` | `((value: Value) => void) \| ((value: Value[]) => void)` |  | Called with the new value, or the new array with `multiple`. |
| `open` | `boolean` |  | Whether the popup is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the popup is open on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `items` | `SelectItem<Value>[]` |  | `{ label, value }` pairs that resolve labels before options mount. |
| `alignItemWithTrigger` | `boolean` | `true` | Lays the selected option over the trigger. Falls back to a dropdown on touch, with nothing selected, or near a viewport edge. |
| `placement` | `Placement` | `'bottom-start'` | Where the popup sits when it is not aligned over the trigger. |
| `sideOffset` | `number` | `4` | Gap to the trigger in px. |

### Select.Trigger

A `button` that toggles the popup. Carries `data-open` or `data-closed`.

### Select.Value

A `span` showing the selected labels, joined with commas.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `ReactNode` |  | Shown while nothing is selected. |
| `children` | `ReactNode \| ((value: unknown[]) => ReactNode)` |  | Replaces the labels. A function gets the selected values in the order picked, and yields to `placeholder` while empty. |

### Select.Portal

Portals its children while the popup is mounted.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| React.RefObject<HTMLElement \| null>` | ``the `Portal` container`` | The element to portal into. |

### Select.Positioner

The floating `div` with `role="listbox"`, and `aria-multiselectable` with `multiple`. Carries `data-side`, which is `none` while aligned over the trigger. Page scroll locks while aligned.

### Select.Popup

Wraps the options. Carries `data-open`, `data-closed`, `data-starting-style` and `data-ending-style`. Its children freeze while it closes.

### Select.Option

A `button` with `role="option"` and `aria-selected`. Carries `data-selected`, `data-active` and `data-disabled`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `unknown` |  | The option value, compared with `Object.is`. |
| `label` | `string` | `String(value)` | Shown in `Select.Value` and matched by typeahead. |
| `disabled` | `boolean` |  | Sets `aria-disabled` and blocks selection. The option stays focusable. |

### Select.Group

A `div` with `role="group"`, labelled by its `Select.GroupLabel`.

### Select.GroupLabel

Names the `Select.Group` it sits in.

### Select.Arrow

An optional `FloatingArrow` `svg` pointing at the trigger. Carries `data-side`.

## Examples

### Single select

```tsx
<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder='Choose a fruit' />
  </Select.Trigger>
  <Select.Positioner>
    <Select.Popup>
      <Select.Option value='apple' label='Apple'>
        Apple
      </Select.Option>
      <Select.Option value='banana' label='Banana'>
        Banana
      </Select.Option>
    </Select.Popup>
  </Select.Positioner>
</Select.Root>
```

## Related

- [Combobox](/docs/components/combobox.md)
- [Menu](/docs/components/menu.md)
- [Portal](/docs/primitives/portal.md)
