Select

A common form component for choosing a predefined value in a dropdown menu.

import * as React from 'react';
import { Select } from '@base-ui-components/react/select';
import styles from './index.module.css';

export default function ExampleSelect() {
  return (
    <Select.Root defaultValue="sans">
      <Select.Trigger className={styles.Select}>
        <Select.Value placeholder="Sans-serif" />
        <Select.Icon className={styles.SelectIcon}>
          <ChevronUpDownIcon />
        </Select.Icon>
      </Select.Trigger>
      <Select.Portal>
        <Select.Positioner className={styles.Positioner} sideOffset={8}>
          <Select.ScrollUpArrow className={styles.ScrollArrow} />
          <Select.Popup className={styles.Popup}>
            <Select.Item className={styles.Item} value="sans">
              <Select.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Select.ItemIndicator>
              <Select.ItemText className={styles.ItemText}>
                Sans-serif
              </Select.ItemText>
            </Select.Item>
            <Select.Item className={styles.Item} value="serif">
              <Select.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Select.ItemIndicator>
              <Select.ItemText className={styles.ItemText}>Serif</Select.ItemText>
            </Select.Item>
            <Select.Item className={styles.Item} value="mono">
              <Select.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Select.ItemIndicator>
              <Select.ItemText className={styles.ItemText}>
                Monospace
              </Select.ItemText>
            </Select.Item>
            <Select.Item className={styles.Item} value="cursive">
              <Select.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Select.ItemIndicator>
              <Select.ItemText className={styles.ItemText}>Cursive</Select.ItemText>
            </Select.Item>
          </Select.Popup>
          <Select.ScrollDownArrow className={styles.ScrollArrow} />
        </Select.Positioner>
      </Select.Portal>
    </Select.Root>
  );
}

function ChevronUpDownIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="8"
      height="12"
      viewBox="0 0 8 12"
      fill="none"
      stroke="currentcolor"
      strokeWidth="1.5"
      {...props}
    >
      <path d="M0.5 4.5L4 1.5L7.5 4.5" />
      <path d="M0.5 7.5L4 10.5L7.5 7.5" />
    </svg>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg fill="currentcolor" width="10" height="10" viewBox="0 0 10 10" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

API reference

Import the component and assemble its parts:

Anatomy

import { Select } from '@base-ui-components/react/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value />
    <Select.Icon />
  </Select.Trigger>

  <Select.Portal>
    <Select.Backdrop />
    <Select.Positioner>
      <Select.ScrollUpArrow />
      <Select.Popup>
        <Select.Arrow />
        <Select.Item>
          <Select.ItemText />
          <Select.ItemIndicator />
        </Select.Item>
        <Select.Separator />
        <Select.Group>
          <Select.GroupLabel />
        </Select.Group>
      </Select.Popup>
      <Select.ScrollDownArrow />
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Root

Groups all parts of the select. Doesn’t render its own HTML element.

Prop	Type	Default
`name`	`string`	`undefined`
`defaultValue`	`Value \| null`	`null`
`value`	`Value \| null`	`undefined`
`onValueChange`	`((value: Value, event: Event \| undefined) => void)`	`undefined`
`defaultOpen`	`boolean`	`false`
`open`	`boolean`	`undefined`
`onOpenChange`	`((open: boolean, event: Event \| undefined) => void)`	`undefined`
`actionsRef`	`RefObject<Actions>`	`undefined`
`alignItemToTrigger`	`boolean`	`true`
`modal`	`boolean`	`true`
`onOpenChangeComplete`	`((open: boolean) => void)`	`undefined`
`transitionStatus`	`TransitionStatus`	`undefined`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`required`	`boolean`	`false`
`id`	`string`	`undefined`
`children`	`ReactNode`	`undefined`

Trigger

A button that opens the select menu. Renders a <div> element.

Prop	Type	Default
`disabled`	`boolean`	`false`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-popup-open`	Present when the corresponding select is open.
`data-pressed`	Present when the trigger is pressed.
`data-disabled`	Present when the select is disabled.
`data-readonly`	Present when the select is readonly.
`data-required`	Present when the select is required.
`data-valid`	Present when the select is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the select is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the select's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the select has been touched (when wrapped in Field.Root).
`data-filled`	Present when the select has a value (when wrapped in Field.Root).
`data-focused`	Present when the select trigger is focused (when wrapped in Field.Root).

Value

A text label of the currently selected item. Renders a <span> element.

Prop	Type	Default
`placeholder`	`string`	`undefined`
`children`	`\| ((label: string, value: any) => ReactNode) \| null`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Icon

An icon that indicates that the trigger button opens a select menu. Renders a <span> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Backdrop

An overlay displayed beneath the menu popup. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-open`	Present when the select is open.
`data-closed`	Present when the select is closed.
`data-starting-style`	Present when the select is animating in.
`data-ending-style`	Present when the select is animating out.

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>.

Prop	Type	Default
`container`	`\| HTMLElement \| RefObject<HTMLElement \| null> \| null`	`undefined`
`children`	`ReactNode`	`undefined`

Positioner

Positions the select menu popup against the trigger. Renders a <div> element.

Prop	Type	Default
`align`	`'center' \| 'end' \| 'start'`	`'center'`
`alignOffset`	`number \| OffsetFunction`	`0`
`side`	`Side`	`'bottom'`
`sideOffset`	`number \| OffsetFunction`	`0`
`arrowPadding`	`number`	`5`
`anchor`	`\| Element \| RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	`undefined`
`collisionBoundary`	`Boundary`	`'clipping-ancestors'`
`collisionPadding`	`Padding`	`5`
`sticky`	`boolean`	`false`
`positionMethod`	`'fixed' \| 'absolute'`	`'absolute'`
`trackAnchor`	`boolean`	`true`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-open`	Present when the select popup is open.
`data-closed`	Present when the select popup is closed.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-side`	Indicates which side the select is positioned relative to the trigger.

CSS Variable	Description
`--anchor-height`	The anchor's height.
`--anchor-width`	The anchor's width.
`--available-height`	The available height between the trigger and the edge of the viewport.
`--available-width`	The available width between the trigger and the edge of the viewport.
`--transform-origin`	The coordinates that this element is anchored to. Used for animations and transitions.

A container for the select items. Renders a <div> element.

Prop	Type	Default
`id`	`string`	`undefined`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-open`	Present when the select is open.
`data-closed`	Present when the select is closed.
`data-side`	Indicates which side the select is positioned relative to the trigger.
`data-starting-style`	Present when the select is animating in.
`data-ending-style`	Present when the select is animating out.

Arrow

Displays an element positioned against the select menu anchor. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-open`	Present when the select popup is open.
`data-closed`	Present when the select popup is closed.
`data-uncentered`	Present when the select arrow is uncentered.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-side`	Indicates which side the select is positioned relative to the trigger.

Item

An individual option in the select menu. Renders a <div> element.

Prop	Type	Default
`label`	`string`	`undefined`
`value`	`any`	`null`
`disabled`	`boolean`	`false`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-selected`	Present when the select item is selected.
`data-highlighted`	Present when the select item is highlighted.
`data-disabled`	Present when the select item is disabled.

ItemText

A text label of the select item. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

ItemIndicator

Indicates whether the select item is selected. Renders a <span> element.

Prop	Type	Default
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Group

Groups related select items with the corresponding label. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

ScrollUpArrow

An element that scrolls the select menu up when hovered. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-direction`	Indicates the direction of the arrow.
`data-side`	Indicates which side the arrow is positioned relative to the select.
`data-visible`	Present when the arrow is visible.

ScrollDownArrow

An element that scrolls the select menu down when hovered. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-direction`	Indicates the direction of the arrow.
`data-side`	Indicates which side the arrow is positioned relative to the select.
`data-visible`	Present when the arrow is visible.

Separator

A separator element accessible to screen readers. Renders a <div> element.

Prop	Type	Default
`orientation`	`Orientation`	`'horizontal'`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`