Select

Overview

Select provides a dropdown menu for selecting a value from a list of options. It’s similar to a native <select> element but with enhanced customization, keyboard navigation, and accessibility features.

Features

Full keyboard navigation
Can be controlled or uncontrolled
Supports custom placeholder
Supports grouping of items
Supports labels and separators
Focus automatically managed
Typeahead support
Works inside forms
Customizable positioning and collision detection
Scrollable content area with scroll buttons

Installation

npm install @radix-ui/react-select

Anatomy

import * as Select from '@radix-ui/react-select';

export default () => (
  <Select.Root>
    <Select.Trigger>
      <Select.Value />
      <Select.Icon />
    </Select.Trigger>
    <Select.Portal>
      <Select.Content>
        <Select.ScrollUpButton />
        <Select.Viewport>
          <Select.Item>
            <Select.ItemText />
            <Select.ItemIndicator />
          </Select.Item>

          <Select.Group>
            <Select.Label />
            <Select.Item>
              <Select.ItemText />
              <Select.ItemIndicator />
            </Select.Item>
          </Select.Group>

          <Select.Separator />
        </Select.Viewport>
        <Select.ScrollDownButton />
        <Select.Arrow />
      </Select.Content>
    </Select.Portal>
  </Select.Root>
);

API Reference

Root

Contains all the select component parts.

string

The controlled value of the select.

string

The value of the select when initially rendered (uncontrolled).

(value: string) => void

Event handler called when the value changes.

boolean

The controlled open state of the select.

boolean

The open state when initially rendered (uncontrolled).

(open: boolean) => void

Event handler called when the open state changes.

'ltr' | 'rtl'

The reading direction. If omitted, inherits from the parent.

string

The name of the select. Submitted with its owning form as part of a name/value pair.

boolean

When true, prevents the user from interacting with the select.

boolean

When true, indicates that the user must select a value before the form can be submitted.

Trigger

The button that toggles the select.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Value

The part that reflects the selected value. By default it will render the selected item’s text. Use the placeholder prop for when there is no value.

React.ReactNode

The content that will be rendered when no value is selected.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Icon

A small icon often displayed next to the value as a visual affordance for the fact it can be opened.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Portal

When used, portals the content part into the body.

HTMLElement

Specify a container element to portal the content into.

Content

The component that pops out when the select is open.

(event: Event) => void

Event handler called when focus moves back after closing.

(event: KeyboardEvent) => void

Event handler called when the escape key is down.

(event: PointerDownOutsideEvent) => void

Event handler called when a pointer event occurs outside the bounds of the component.

'item-aligned' | 'popper'

default:"'item-aligned'"

The positioning mode to use.

item-aligned: Positions content aligned with the selected item
popper: Positions content using a positioning engine

'top' | 'right' | 'bottom' | 'left'

default:"'bottom'"

The preferred side of the trigger to render against when open (only available when position is set to popper).

number

default:"0"

The distance in pixels from the trigger (only available when position is set to popper).

'start' | 'center' | 'end'

default:"'start'"

The preferred alignment against the trigger (only available when position is set to popper).

number

default:"0"

An offset in pixels from the “start” or “end” alignment options (only available when position is set to popper).

boolean

default:"true"

When true, overrides the side and align preferences to prevent collisions (only available when position is set to popper).

Element | Element[]

default:"[]"

The element(s) used as collision boundary (only available when position is set to popper).

number | Partial<Record<Side, number>>

default:"0"

The distance in pixels from the boundary edges (only available when position is set to popper).

number

default:"0"

The padding between the arrow and the edges of the content (only available when position is set to popper).

'partial' | 'always'

default:"'partial'"

The sticky behavior on the align axis (only available when position is set to popper).

boolean

default:"false"

Whether to hide the content when the trigger becomes fully occluded (only available when position is set to popper).

Viewport

The scrolling viewport that contains all of the items.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Item

The component that contains the select items.

string

required

The value given as data when submitted with a name.

boolean

When true, prevents the user from interacting with the item.

string

Optional text used for typeahead purposes. By default the typeahead behavior will use the text content.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

ItemText

The textual part of the item. It should only contain the text you want to announce to assistive technology when the item is selected.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

ItemIndicator

Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

ScrollUpButton

An optional button used to indicate when the viewport can be scrolled up.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

ScrollDownButton

An optional button used to indicate when the viewport can be scrolled down.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Group

Used to group multiple items. Use in conjunction with Label to ensure good accessibility via automatic labelling.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Label

Used to render the label of a group. It won’t be focusable using arrow keys.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Separator

Used to visually separate items in the select.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Arrow

An optional arrow element to render alongside the content.

number

default:"10"

The width of the arrow in pixels.

number

default:"5"

The height of the arrow in pixels.

boolean

default:"false"

Change the default rendered element for the one passed as a child.

Example

import * as Select from '@radix-ui/react-select';
import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from '@radix-ui/react-icons';
import './styles.css';

export default () => (
  <Select.Root>
    <Select.Trigger className="SelectTrigger" aria-label="Food">
      <Select.Value placeholder="Select a fruit…" />
      <Select.Icon className="SelectIcon">
        <ChevronDownIcon />
      </Select.Icon>
    </Select.Trigger>
    <Select.Portal>
      <Select.Content className="SelectContent">
        <Select.ScrollUpButton className="SelectScrollButton">
          <ChevronUpIcon />
        </Select.ScrollUpButton>
        <Select.Viewport className="SelectViewport">
          <Select.Group>
            <Select.Label className="SelectLabel">Fruits</Select.Label>
            <Select.Item value="apple" className="SelectItem">
              <Select.ItemText>Apple</Select.ItemText>
              <Select.ItemIndicator className="SelectItemIndicator">
                <CheckIcon />
              </Select.ItemIndicator>
            </Select.Item>
            <Select.Item value="banana" className="SelectItem">
              <Select.ItemText>Banana</Select.ItemText>
              <Select.ItemIndicator className="SelectItemIndicator">
                <CheckIcon />
              </Select.ItemIndicator>
            </Select.Item>
            <Select.Item value="blueberry" className="SelectItem">
              <Select.ItemText>Blueberry</Select.ItemText>
              <Select.ItemIndicator className="SelectItemIndicator">
                <CheckIcon />
              </Select.ItemIndicator>
            </Select.Item>
          </Select.Group>

          <Select.Separator className="SelectSeparator" />

          <Select.Group>
            <Select.Label className="SelectLabel">Vegetables</Select.Label>
            <Select.Item value="carrot" className="SelectItem">
              <Select.ItemText>Carrot</Select.ItemText>
              <Select.ItemIndicator className="SelectItemIndicator">
                <CheckIcon />
              </Select.ItemIndicator>
            </Select.Item>
            <Select.Item value="potato" className="SelectItem">
              <Select.ItemText>Potato</Select.ItemText>
              <Select.ItemIndicator className="SelectItemIndicator">
                <CheckIcon />
              </Select.ItemIndicator>
            </Select.Item>
          </Select.Group>
        </Select.Viewport>
        <Select.ScrollDownButton className="SelectScrollButton">
          <ChevronDownIcon />
        </Select.ScrollDownButton>
      </Select.Content>
    </Select.Portal>
  </Select.Root>
);

import { useState } from 'react';
import * as Select from '@radix-ui/react-select';

export default () => {
  const [value, setValue] = useState('apple');

  return (
    <Select.Root value={value} onValueChange={setValue}>
      <Select.Trigger>
        <Select.Value />
      </Select.Trigger>
      <Select.Portal>
        <Select.Content>
          <Select.Viewport>
            <Select.Item value="apple">
              <Select.ItemText>Apple</Select.ItemText>
            </Select.Item>
            <Select.Item value="banana">
              <Select.ItemText>Banana</Select.ItemText>
            </Select.Item>
          </Select.Viewport>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
};

Accessibility

Adheres to the ListBox WAI-ARIA design pattern.

Keyboard Interactions

Space - When focus is on the trigger, opens the select and focuses the selected item.
Enter - When focus is on the trigger, opens the select and focuses the first item.
ArrowDown - When focus is on the trigger, opens the select. When focus is on an item, moves focus to the next item.
ArrowUp - When focus is on the trigger, opens the select. When focus is on an item, moves focus to the previous item.
Esc - Closes the select and moves focus to the trigger.
A-Z - When focus is on the trigger or an item, opens the select (if closed) and focuses the first item starting with that letter.

Overlays

Navigation

Forms

Layout

Data Display

Utilities

Overview

Features

Installation

Anatomy

API Reference

Root

Trigger

Value

Icon

Portal

Content

Viewport

Item

ItemText

ItemIndicator

ScrollUpButton

ScrollDownButton

Group

Label

Separator

Arrow

Example

Accessibility

Keyboard Interactions

​Overview

​Features

​Installation

​Anatomy

​API Reference

​Root

​Trigger

​Value

​Icon

​Portal

​Content

​Viewport

​Item

​ItemText

​ItemIndicator

​ScrollUpButton

​ScrollDownButton

​Group

​Label

​Separator

​Arrow

​Example

​Accessibility

​Keyboard Interactions

Overview

Features

Installation

Anatomy

API Reference

Root

Trigger

Value

Icon

Portal

Content

Viewport

Item

ItemText

ItemIndicator

ScrollUpButton

ScrollDownButton

Group

Label

Separator

Arrow

Example

Accessibility

Keyboard Interactions