On this page
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
| Guidance | Practice |
|---|---|
| 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 | Description |
|---|---|---|
multiple | boolean | Makes the value an array. Picking toggles an option and keeps the popup open.Default: false |
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 | Whether the popup is open on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
items | SelectItem<Value>[] | { label, value } pairs that resolve labels before options mount. |
alignItemWithTrigger | boolean | Lays the selected option over the trigger. Falls back to a dropdown on touch, with nothing selected, or near a viewport edge.Default: true |
placement | Placement | Where the popup sits when it is not aligned over the trigger.Default: 'bottom-start' |
sideOffset | number | Gap to the trigger in px.Default: 4 |
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 | 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 | Description |
|---|---|---|
root | HTMLElement | null | React.RefObject<HTMLElement | null> | The element to portal into.Default: the `Portal` container |
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 | Description |
|---|---|---|
value | unknown | The option value, compared with Object.is. |
label | string | Shown in Select.Value and matched by typeahead.Default: String(value) |
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
<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>