Skip to content
Mosaic
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

GuidancePractice
DoPass every choice as items on the root, so the closed trigger can show the selected label.
DoUse variant='ghost' and an aria-label for a trigger in a table row.
DoWrap it in Field.Root with a Field.Label in a form, instead of labelling the trigger by hand.
Don’tUse it when the user types to filter options. Use Combobox instead.

API reference

Select.Root

Holds the selection and the items. Renders no element.

PropTypeDescription
itemsSelectItem<Value>[]{ value, label, description?, disabled? } for every choice. label drives typeahead.
multiplebooleanMakes the value an array. Picking an option toggles it and keeps the popup open.Default: false
valueValue | Value[] | nullThe selection, when controlled. An array with multiple.
defaultValueValue | Value[] | nullThe selection on mount, when uncontrolled.
onValueChange((value: Value) => void) | ((value: Value[]) => void)Called with the new selection.
openbooleanOpen state, when controlled.
defaultOpenbooleanOpen state on mount.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
alignItemWithTriggerbooleanOverlays 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'
sideOffsetnumberGap 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

PropTypeDescription
variantSelectTriggerVariantoutline for a form control, ghost for a dense surface such as a table row.Default: 'outline'
placeholderReact.ReactNodeShown while nothing is selected.
childrenReact.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

PropTypeDescription
portalRootSelectPortalProps['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

PropTypeDescription
valueunknownThe value this option selects.
labelstringShown in the row and the trigger; drives typeahead.
descriptionstringA secondary line under the label.
disabledbooleanKeeps the option focusable but not selectable.
childrenReact.ReactNodeComposes 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

TSX
<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

TSX
<Select.Root items={roles} value={member.role} onValueChange={onChangeRole}>
  <Select.Trigger variant='ghost' aria-label={label} />
  <Select.Popup />
</Select.Root>