On this page
Select
A dropdown that picks one value, or several with multiple, from a list of items. Keyboard navigation and typeahead; values can be any type and compare with Object.is. Inside a Field the trigger takes the field id, label, disabled, required, invalid and message wiring. Each part is also exported on its own, such as SelectTrigger.
Use for
- picking one option from a list, such as a role
- picking several options from a list
- a compact dropdown in a table row
- options with an icon, avatar or description
Practices
| Guidance | Practice |
|---|---|
| Do | Pass every choice as items on the root, so the closed trigger can show the selected label. |
| Do | Use variant='ghost' and an aria-label for a trigger in a table row. |
| Do | Wrap it in Field.Root with a Field.Label in a form, instead of labelling the trigger by hand. |
| Don’t | Use it when the user types to filter options. Use Combobox instead. |
API reference
Select.Root
Holds the selection and the items. Renders no element.
| Prop | Type | Description |
|---|---|---|
items | SelectItem<Value>[] | { value, label, description?, disabled? } for every choice. label drives typeahead. |
multiple | boolean | Makes the value an array. Picking an option toggles it and keeps the popup open.Default: false |
value | Value | Value[] | null | The selection, when controlled. 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 selection. |
open | boolean | Open state, when controlled. |
defaultOpen | boolean | Open state on mount.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
alignItemWithTrigger | boolean | Overlays the selected option on the trigger, like a native select. Falls back below the trigger on touch or near an edge.Default: true, or false when `multiple` or any item has a description |
placement | 'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | Side and alignment when not aligned with the trigger.Default: 'bottom-start' |
sideOffset | number | Gap in px between trigger and popup.Default: 4 |
Select.Trigger
Opens the listbox and shows the selected label, with a chevron (cl-select-trigger-icon). Renders a neutral md Button, or the render element. Carries data-variant, and data-open or data-closed.
Slot: cl-select-trigger
| Prop | Type | Description |
|---|---|---|
variant | SelectTriggerVariant | outline for a form control, ghost for a dense surface such as a table row.Default: 'outline' |
placeholder | React.ReactNode | Shown while nothing is selected. |
children | React.ReactNode | ((value: unknown[]) => React.ReactNode) | A function receives the selected values and renders inside the value slot (cl-select-value); anything else replaces it. |
Select.Popup
The floating role='listbox', with a scrolling viewport (cl-select-viewport) in a positioner (cl-select-positioner). Renders one Select.Option per item unless given children.
Slot: cl-select-popup
| Prop | Type | Description |
|---|---|---|
portalRoot | SelectPortalProps['root'] | Container the listbox portals into.Default: document.body |
Select.Option
One role='option' with a check (cl-select-option-indicator) when selected. Carries data-selected, data-active, data-disabled, and data-described when it has a description.
Slot: cl-select-option
| Prop | Type | Description |
|---|---|---|
value | unknown | The value this option selects. |
label | string | Shown in the row and the trigger; drives typeahead. |
description | string | A secondary line under the label. |
disabled | boolean | Keeps the option focusable but not selectable. |
children | React.ReactNode | Composes the row from Select.Media and Select.Content. Without it the row shows label and description. |
Select.Media
A square leading column for an icon, image or avatar.
Slot: cl-select-option-media
Select.Content
Stacks the label and description beside the media.
Slot: cl-select-option-content
Select.Label
The option's name, on one line. Names the option.
Slot: cl-select-option-label
Select.Description
A secondary line under the label. Describes the option without joining its name.
Slot: cl-select-option-description
Examples
In a field
<Field.Root>
<Field.Label>Role</Field.Label>
<Select.Root items={roles} value={role} onValueChange={setRole}>
<Select.Trigger placeholder={m.rolePlaceholder} />
<Select.Popup />
</Select.Root>
</Field.Root>In a table row
<Select.Root items={roles} value={member.role} onValueChange={onChangeRole}>
<Select.Trigger variant='ghost' aria-label={label} />
<Select.Popup />
</Select.Root>