shadcn.io is not affiliated with official shadcn/ui

Components

Free

Select for React

Q: How do I submit a Select with a form?

Set name on Select to the field name the form should receive. The selected value is submitted through a hidden field, so the visible trigger does not have to be a native select, and Select stays inside the form. Set required when a choice is mandatory.

Open a short list of known options from a button and keep the picked label on it. For React with Base UI, when a typed value the server has never seen would be wrong.

Known options live in a closed list. A button opens it and shows the one you picked.

Use it when the list is short enough to scan and people should not type their own value. If they need to filter a long catalog, use a Combobox. In React, you hold the chosen value when the form is controlled, and Base UI shows it on the trigger.

PreviewCode

Installation

Free with an account. It carries your token, so the CLI installs everything in one go.

Google GitHub

Use email insteadNo credit card

Anatomy

SelectRoot
├── SelectLabel
├── SelectClearTrigger
├── SelectItem
│   ├── SelectItemText
│   ├── SelectItemIndicator
│   └── SelectGroup
│       └── SelectGroupLabel
├── SelectList
├── SelectContent
│   └── SelectPositioner
├── SelectTrigger
│   └── SelectIndicator
└── SelectValue

Usage

import {
  Select, SelectContent, SelectGroup, SelectItem, SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

const items = [
  { label: "Select a fruit", value: null },
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Blueberry", value: "blueberry" },
];

const SelectDemo = () => (
  <Select items={items}>
    <SelectTrigger className="w-48">
      <SelectValue />
    </SelectTrigger>
    <SelectContent>
      <SelectGroup>
        {items.map((item) => (
          <SelectItem key={item.value} value={item.value}>
            {item.label}
          </SelectItem>
        ))}
      </SelectGroup>
    </SelectContent>
  </Select>
);

Accessibility

Space: When focus is on trigger, opens the select and focuses the first selected item. When focus is on the content, selects the highlighted item.
Enter: When focus is on trigger, opens the select and focuses the first selected item. When focus is on content, selects the focused item.
Arrow Down: When focus is on trigger, opens the select. When focus is on content, moves focus to the next item.
Arrow Up: When focus is on trigger, opens the select. When focus is on content, moves focus to the previous item.
EscEscape: Closes the select and moves focus to trigger.
A-Z: When focus is on trigger, selects the item whose label starts with the typed character. When focus is on the listbox, moves focus to the next item with a label that starts with the typed character.
a-z: When focus is on trigger, selects the item whose label starts with the typed character. When focus is on the listbox, moves focus to the next item with a label that starts with the typed character.
Arrow Left: Move left.
Arrow Right: Move right.
Home: Go to the start.
End: Go to the end.

Demos

Align Item

A switch above the fruit list turns item alignment on and off. On, the open popup lines the selected row up with the trigger. Off, the popup sits against an edge instead, which stays put once the list is long enough to scroll, while item alignment keeps a short list's choice under the pointer. The prop differs by base, and the FAQ on this page names it.

PreviewCode

Groups

Fruits and vegetables are two groups, each with a heading, and a SelectSeparator between them. Group a list when the options are one choice but people scan by category, such as timezones, roles, or cuisines. The separator is only a visual break, not a second label. Skip both when you have a handful of peers and a heading would repeat the field label.

PreviewCode

Scrollable

The list is timezones, grouped by region, and longer than the popup, so the content scrolls rather than growing to fit every zone. Use a scrolling select when the catalog is long but people still choose by looking, not by typing a filter. If they know the name and will type it, a Combobox is faster than hunting through a scroll. Headings still help once the list moves.

PreviewCode

Disabled

disabled on the select keeps the trigger from opening, and the control reads as unavailable. Use it when an earlier answer is missing, or when this user cannot change a value that is already set. Do not disable an option to hide it: remove it, or leave it enabled and explain the constraint. A disabled select still shows its placeholder, so the field does not look missing.

PreviewCode

Invalid

The fruit field is in an error state: a label, an invalid trigger, and a FieldError that says to select a fruit. Use this after submit when a choice was required and none was made. The sentence is the error, and the color only supports it. How you mark the control invalid differs by base, the FAQ names the prop, and the message belongs in a Field.

PreviewCode

Rtl

dir is rtl, and the options are Arabic names for the same fruits. The trigger, the value, and the popup follow that direction, so the text and the indicator start on the right. Set dir on the select when only this field is right-to-left, and on the document when the whole page is. A single control with dir will not fix the headings around it.

PreviewCode

FAQ

How do I control the selected Select value in React?

Keep the selection in state and pass it back to Select, or use the default prop when the first choice is enough. The shape of that value depends on the base. The value is a single item value, or an array when multiple is set. Pass value, and onValueChange receives that value, pass defaultValue for the uncontrolled case, pass items so SelectValue can show the label, and set value on each SelectItem.

How do I show a placeholder in a Select?

The empty label is not a selected value. Show it until someone chooses an item, then replace it with the item label, so people can tell the prompt from a real choice. Set placeholder on SelectValue, or include an items entry whose value is null so that row reads as the prompt. SelectValue uses items to turn the stored value into a label.

How do I align a Select popup with Base UI?

The popup can line the selected item up with the trigger, or sit against an edge. The Align Item demo is the place to compare those, except on React Aria, which only anchors the popup. alignItemWithTrigger on SelectContent defaults to lining the selected item up with the trigger. Set it to false for edge alignment, and side defaults to bottom.

How do I submit a Select with a form?

Set name on Select to the field name the form should receive. The selected value is submitted through a hidden field, so the visible trigger does not have to be a native select, and Select stays inside the form. Set required when a choice is mandatory.

How do I show a Select as invalid?

Pair the control with Field so the message sits under the trigger, and keep that message in text because color alone is not the error. The Invalid demo is the pattern to copy. Set data-invalid on Field and aria-invalid on SelectTrigger.

Should I use a Select, a Combobox, or a Native Select?

Use Select for one choice from a list that stays closed until it is opened. Use a Combobox when people need to type and filter. Use a Native Select when you want the browser's own menu, which is often the better control on a phone.

Can I use a Select from the keyboard?

Yes. From the trigger, Enter, Space, or Arrow Down opens the list. Arrow keys move between items, Enter or Space selects the highlighted one, and Escape closes the list and returns focus to the trigger. Typing a letter moves to a label that starts with that letter.

How do I install Select in React?

Run the command in the Installation section above. It adds Select and its parts to your ui folder. Import from that folder when the command finishes, instead of copying the source by hand, and rerun the command later if you want the latest files. The command uses the shadcn CLI.

API Reference

Select

PropType

open?boolean

Whether the select popup is currently open.

defaultOpen?boolean

Whether the select popup is initially open. To render a controlled select popup, use the open prop instead.

Default: false

onOpenChange?(open: boolean, eventDetails: SelectRootOpenChangeEventDetails) → void

Event handler called when the select popup is opened or closed.

Type

(open: boolean, eventDetails: SelectRootOpenChangeEventDetails) → void

Parameters

open – boolean

eventDetails – SelectRootOpenChangeEventDetails

Returns

void

value?SelectInputValue<Value, Multiple> | null

The value of the select. Use when controlled.

Type: SelectInputValue<Value, Multiple> | null

defaultValue?SelectInputValue<Value, Multiple> | null

The uncontrolled value of the select when it's initially rendered. To render a controlled select, use the value prop instead.

Type: SelectInputValue<Value, Multiple> | null

onValueChange?(value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) → void

Event handler called when the value of the select changes.

Type

(value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) → void

Parameters

value – SelectOutputValue<Value

Multiple> | (Multiple extends true ? never – null)

eventDetails – SelectRootChangeEventDetails

Returns

void

actionsRef?React.RefObject<SelectRootActions | null>

A ref to imperative actions. - unmount: Ends the closing phase of the select after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the select completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal. - close: Closes the select imperatively when called.

Type: React.RefObject<SelectRootActions | null>

autoComplete?string

Provides a hint to the browser for autofill.

disabled?boolean

Whether the component should ignore user interaction.

Default: false

form?string

Identifies the form that owns the hidden input. Useful when the select is rendered outside the form.

highlightItemOnHover?boolean

Whether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state.

Default: true

id?string

The id of the Select.

inputRef?React.Ref<HTMLInputElement>

A ref to access the hidden input element.

Type: React.Ref<HTMLInputElement>

isItemEqualToValue?(itemValue: Value, value: Value) → boolean

Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to Object.is comparison.

Type

(itemValue: Value, value: Value) → boolean

Parameters

itemValue – Value

value – Value

Returns

boolean

items?Record<string, React.ReactNode> | ReadonlyArray<{ label: React.ReactNode; value: any; }> | ReadonlyArray<Group<any>>

Data structure of the items rendered in the select popup. When specified, <Select.Value> renders the label of the selected item instead of the raw value. ``tsx const items = { sans:Sans-serif, serif:Serif, mono:Monospace, cursive:Cursive, };<Select.Root items={items} />``

Type: Record<string, React.ReactNode> | ReadonlyArray<{ label: React.ReactNode; value: any; }> | ReadonlyArray<Group<any>>

itemToStringLabel?(itemValue: Value) → string

When the item values are objects (<Select.Item value={object}>), this function converts the object value to a string representation for display in the trigger. If the shape of the object is { value, label }, the label will be used automatically without needing to specify this prop.

Parameters: itemValue – Value
Returns: string

itemToStringValue?(itemValue: Value) → string

When the item values are objects (<Select.Item value={object}>), this function converts the object value to a string representation for form submission. If the shape of the object is { value, label }, the value will be used automatically without needing to specify this prop.

Parameters: itemValue – Value
Returns: string

modal?boolean

Determines if the select enters a modal state when open. - true: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled. - false: user interaction with the rest of the document is allowed. On touch devices, a true modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.

Default: true

multiple?Multiple

Whether multiple items can be selected.

Default: false

name?string

Identifies the field when a form is submitted.

onOpenChangeComplete?(open: boolean) → void

Event handler called after any animations complete when the select popup is opened or closed.

Parameters: open – boolean
Returns: void

readOnly?boolean

Whether the user should be unable to choose a different option from the select popup.

Default: false

required?boolean

Whether the user must choose a value before submitting a form.

Default: false

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

AttributeType

data-invalid?string

Present when invalid is true.

data-readonly?string

Present when readOnly is true.

SelectPositioner

<div>

PropType

align?"start" | "center" | "end"

How to align the popup relative to the specified side.

Type: "start" | "center" | "end"
Default: "center"

alignItemWithTrigger?boolean

Whether the positioner overlaps the trigger so the selected item's text is aligned with the trigger's value text. This only applies to mouse input and is automatically disabled if there is not enough space.

Default: true

alignOffset?number | OffsetFunction

Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: - data.anchor: the dimensions of the anchor element with properties width and height. - data.positioner: the dimensions of the positioner element with properties width and height. - data.side: which side of the anchor element the positioner is aligned against. - data.align: how the positioner is aligned relative to the specified side. ``jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side ===top || side === bottom? anchor.width : anchor.height; }} />``

Type: number | OffsetFunction
Default: 0

An element to position the popup against. By default, the popup will be positioned against the trigger.

Type: Element | null | VirtualElement | React.RefObject<Element | null> | (() → Element | VirtualElement | null)

arrowPadding?number

Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.

Default: 5

collisionAvoidance?SideFlipMode | SideShiftMode

Determines how to handle collisions when positioning the popup. side controls overflow on the preferred placement axis (top/bottom or left/right): - flip: keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right). - shift: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - none: do not correct side-axis overflow. align controls overflow on the alignment axis (start/center/end): - flip: keep side, but swap start and end when the requested alignment overflows. - shift: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - none: do not correct alignment-axis overflow. fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - start: allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR). - end: allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR). - none: do not fallback to the perpendicular axis. When side is shift, explicitly setting align only supports shift or none. If align is omitted, it defaults to flip. ``jsx <Positioner collisionAvoidance={{ side:shift, align:shift, fallbackAxisSide:none, }} />``

Type: SideFlipMode | SideShiftMode

collisionBoundary?"clipping-ancestors" | Element | Element[] | Rect

An element or a rectangle that delimits the area that the popup is confined to.

Type: "clipping-ancestors" | Element | Element[] | Rect
Default: "clipping-ancestors"

collisionPadding?Padding

Additional space to maintain from the edge of the collision boundary.

Default: 5

disableAnchorTracking?boolean

Whether to disable the popup from tracking any layout shift of its positioning anchor.

Default: false

positionMethod?"absolute" | "fixed"

Determines which CSS position property to use.

Type: "absolute" | "fixed"
Default: "absolute"

Which side of the anchor element to align the popup against. May automatically change to avoid collisions.

Type: "top" | "bottom" | "left" | "right" | "inline-end" | "inline-start"
Default: "bottom"

sideOffset?number | OffsetFunction

Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: - data.anchor: the dimensions of the anchor element with properties width and height. - data.positioner: the dimensions of the positioner element with properties width and height. - data.side: which side of the anchor element the positioner is aligned against. - data.align: how the positioner is aligned relative to the specified side. ``jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side ===top || side === bottom? anchor.height : anchor.width; }} />``

Type: number | OffsetFunction
Default: 0

sticky?boolean

Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.

Default: false

CSS variableType

--anchor-widthstring

The anchor's width.

--available-heightstring

The height left between the anchor and the viewport's edge.

--transform-originstring

Where the content scales from, on its trigger's side.

SelectTrigger

<button> data-slot="select-trigger"

PropType

disabled?boolean

Whether the component should ignore user interaction.

nativeButton?boolean

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

Default: true

size?"sm" | "default"

The size.

Type: "sm" | "default"
Default: "default"

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

AttributeType

data-disabled?string

Present when disabled is true.

data-invalid?string

Present when invalid is true.

data-placeholder-shown?string

Present when placeholder shown.

data-placementstring

The content's placement on its trigger, such as bottom-start.

data-readonly?string

Present when readOnly is true.

data-side"top" | "right" | "bottom" | "left"

The side of the trigger the content sits on.

Type: "top" | "right" | "bottom" | "left"

data-size?string

Mirrors size.

data-state"open" | "closed"

"open" or "closed".

Type: "open" | "closed"

SelectItem

<div> data-slot="select-item"

PropType

disabled?boolean

Whether the component should ignore user interaction.

Default: false

label?string

Specifies the text label to use when the item is matched during keyboard text navigation. Defaults to the item text content if not provided.

nativeButton?boolean

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

Default: false

value?any

A unique value that identifies this select item.

Default: null

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

AttributeType

data-disabled?string

Present when disabled is true.

data-highlighted?string

Present when highlighted is true.

data-state"checked" | "unchecked"

"checked" or "unchecked".

Type: "checked" | "unchecked"

data-valueboolean

Value of value.

SelectItemText

<div>

AttributeType

data-disabled?string

Present when disabled is true.

data-highlighted?string

Present when highlighted is true.

data-state"checked" | "unchecked"

"checked" or "unchecked".

Type: "checked" | "unchecked"

SelectItemIndicator

<span>

PropType

keepMounted?boolean

Whether to keep the HTML element in the DOM when the item is not selected.

AttributeType

data-state"checked" | "unchecked"

"checked" or "unchecked".

Type: "checked" | "unchecked"

SelectList

<div>

CSS variableType

--anchor-widthstring

The anchor's width.

--available-heightstring

The height left between the anchor and the viewport's edge.

--transform-originstring

Where the content scales from, on its trigger's side.

SelectGroup

<div> data-slot="select-group"

PropType

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

SelectValue

<span> data-slot="select-value"

PropType

children?React.ReactNode | ((value: any) → React.ReactNode)

Accepts a function that returns a ReactNode to format the selected value. Treat the value as read-only: in multiple mode it may be a shared frozen array when nothing is selected. ``tsx<Select.Value>{(value: string | null) => value ? labels[value] :No value} </Select.Value>``

Type: React.ReactNode | ((value: any) → React.ReactNode)

placeholder?React.ReactNode

The placeholder value to display when no value is selected. This is overridden by children if specified, or by a null item's label in items.

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

SelectContent

<div> data-slot="select-content"

PropType

Determines the element to focus when the select popup is closed. - false: Do not move focus. - true: Move focus based on the default behavior (trigger or previously focused element). - RefObject: Move focus to the ref element. - function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing.

Type: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) → boolean | HTMLElement | null | void)

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

AttributeType

data-align-trigger?string

Mirrors alignItemWithTrigger.

CSS variableType

--anchor-widthstring

The anchor's width.

--available-heightstring

The height left between the anchor and the viewport's edge.

--transform-originstring

Where the content scales from, on its trigger's side.

SelectLabel

<div> data-slot="select-label"

PropType

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

SelectSeparator

<div> data-slot="select-separator"

PropType

orientation?"horizontal" | "vertical"

The orientation of the separator.

Type: "horizontal" | "vertical"
Default: "horizontal"

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

SelectScrollUpButton

<div> data-slot="select-scroll-up-button"

PropType

keepMounted?boolean

Whether to keep the HTML element in the DOM while the select popup is not scrollable.

Default: false

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

SelectScrollDownButton

<div> data-slot="select-scroll-down-button"

PropType

keepMounted?boolean

Whether to keep the HTML element in the DOM while the select popup is not scrollable.

Default: false

render?ReactElement | ((props: object, state: object) => ReactElement)

Replace the host element or compose it with another component.

Type: ReactElement | ((props: object, state: object) => ReactElement)

className?string

Merged with the part's classes.

With other components

Free
Field
Inputs
Label, description, error
Free
Label
Inputs
Name the trigger
Free
Input
Inputs
Same form row
Free
Button Group
Buttons
Compact filter bar
Free
Card
Layout
Settings on a card
Free
Tooltip
Overlays
Why an option is disabled

Free
Native Select
Selection
Phone system picker
Free
Combobox
Selection
Search a long list
Free
Dropdown Menu
Menus
Actions, not values
Free
Command
Overlays
Palette with search
Free
Radio Group
Selection
Every option visible
Free
Direction
Layout
RTL for the page

All 105 components

Installation

Anatomy

Usage

Accessibility

Demos

Align Item

Groups

Scrollable

Disabled

Invalid

Rtl

FAQ

How do I control the selected Select value in React?

How do I show a placeholder in a Select?

How do I align a Select popup with Base UI?

How do I submit a Select with a form?

How do I show a Select as invalid?

Should I use a Select, a Combobox, or a Native Select?

Can I use a Select from the keyboard?

How do I install Select in React?

API Reference

Select

SelectPositioner

SelectTrigger

SelectItem

SelectItemText

SelectItemIndicator

SelectList

SelectGroup

SelectValue

SelectContent

SelectLabel

SelectSeparator

SelectScrollUpButton

SelectScrollDownButton

With other components

Related