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.Popup className={styles.Popup}>
            <Select.Arrow className={styles.Arrow}>
              <ArrowSvg />
            </Select.Arrow>
            <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.Positioner>
      </Select.Portal>
    </Select.Root>
  );
}

function ArrowSvg(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="20" height="10" viewBox="0 0 20 10" fill="none" {...props}>
      <path
        d="M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z"
        className={styles.ArrowFill}
      />
      <path
        d="M8.99542 1.85876C9.75604 1.17425 10.9106 1.17422 11.6713 1.85878L16.5281 6.22989C17.0789 6.72568 17.7938 7.00001 18.5349 7.00001L15.89 7L11.0023 2.60207C10.622 2.2598 10.0447 2.2598 9.66436 2.60207L4.77734 7L2.13171 7.00001C2.87284 7.00001 3.58774 6.72568 4.13861 6.22989L8.99542 1.85876Z"
        className={styles.ArrowOuterStroke}
      />
      <path
        d="M10.3333 3.34539L5.47654 7.71648C4.55842 8.54279 3.36693 9 2.13172 9H0V8H2.13172C3.11989 8 4.07308 7.63423 4.80758 6.97318L9.66437 2.60207C10.0447 2.25979 10.622 2.2598 11.0023 2.60207L15.8591 6.97318C16.5936 7.63423 17.5468 8 18.5349 8H20V9H18.5349C17.2998 9 16.1083 8.54278 15.1901 7.71648L10.3333 3.34539Z"
        className={styles.ArrowInnerStroke}
      />
    </svg>
  );
}

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 place its parts the following way:

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
`alignItemToTrigger`	`boolean`	`true`
`defaultOpen`	`boolean`	`false`
`defaultValue`	`any`	`null`
`disabled`	`boolean`	`false`
`name`	`string`	`undefined`
`onOpenChange`	`function`	`undefined`
`onValueChange`	`function`	`undefined`
`open`	`boolean`	`undefined`
`readOnly`	`boolean`	`false`
`required`	`boolean`	`false`
`value`	`any`	`undefined`

Trigger

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

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`disabled`	`boolean`	`false`
`label`	`string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Value

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

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`placeholder`	`string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.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) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Backdrop

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

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

Portal

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

Prop	Type	Default
`container`	`React.Ref \| HTMLElement \| null`	`undefined`

Positioner

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

Prop	Type	Default
`align`	`'start' \| 'center' \| 'end'`	`'start'`
`alignOffset`	`number`	`0`
`anchor`	`\| React.Ref \| Element \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	`undefined`
`arrowPadding`	`number`	`5`
`className`	`string \| (state) => string`	`undefined`
`collisionBoundary`	`\| 'clippingAncestors' \| Element \| Element[] \| Rect`	`'clipping-ancestors'`
`collisionPadding`	`number \| Rect`	`5`
`positionMethod`	`'absolute' \| 'fixed'`	`'absolute'`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`
`side`	`\| 'bottom' \| 'inline-end' \| 'inline-start' \| 'left' \| 'right' \| 'top'`	`'bottom'`
`sideOffset`	`number`	`0`
`sticky`	`boolean`	`false`
`trackAnchor`	`boolean`	`true`

CSS Variable	Type
`--anchor-height`	`number`
`--anchor-width`	`number`
`--available-height`	`number`
`--available-width`	`number`
`--transform-origin`	`string`

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

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`id`	`string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Arrow

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

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Item

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

Prop	Type	Default
`disabled`	`boolean`	`false`
`label`	`string`	`undefined`
`value`	`any`	`null`

Item Text

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

Prop	Type	Default

Item Indicator

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

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

Group

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

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Group Label

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

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Scroll Up Arrow

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

Prop	Type	Default
`keepMounted`	`boolean`	`false`

Scroll Down Arrow

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

Prop	Type	Default
`keepMounted`	`boolean`	`false`

Separator

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

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`