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

GuidancePractice
DoPass label on each Select.Option whose value is not display text. It falls back to String(value).
DoPass items when Select.Value must show a label before the options mount, such as on first render.
DoPut a Select.GroupLabel inside every Select.Group. It throws outside one.
Don’tPass id to Select.Positioner. The primitive owns it to pair the trigger’s aria-controls.
Don’tExpect items to render options. It only resolves labels; render each Select.Option.
Don’tUse 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.

PropTypeDescription
multiplebooleanMakes the value an array. Picking toggles an option and keeps the popup open.Default: false
valueValue | Value[] | nullThe selection, when controlled. null for none, or an array with multiple.
defaultValueValue | Value[] | nullThe selection on mount, when uncontrolled.
onValueChange((value: Value) => void) | ((value: Value[]) => void)Called with the new value, or the new array with multiple.
openbooleanWhether the popup is open, when controlled.
defaultOpenbooleanWhether the popup is open on mount, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
itemsSelectItem<Value>[]{ label, value } pairs that resolve labels before options mount.
alignItemWithTriggerbooleanLays the selected option over the trigger. Falls back to a dropdown on touch, with nothing selected, or near a viewport edge.Default: true
placementPlacementWhere the popup sits when it is not aligned over the trigger.Default: 'bottom-start'
sideOffsetnumberGap 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.

PropTypeDescription
placeholderReactNodeShown while nothing is selected.
childrenReactNode | ((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.

PropTypeDescription
rootHTMLElement | 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.

PropTypeDescription
valueunknownThe option value, compared with Object.is.
labelstringShown in Select.Value and matched by typeahead.Default: String(value)
disabledbooleanSets 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>