Select

Select lets users choose one value from a short list in a custom-styled popup. Use Combobox for long searchable lists and NativeSelect when native browser behavior is more important than custom styling.

Basic usage

Code

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select status" />
  </SelectTrigger>

  <SelectContent>
    <SelectGroup>
      <SelectLabel>Order status</SelectLabel>
      <SelectItem value="draft">Draft</SelectItem>
      <SelectItem value="confirmed">Confirmed</SelectItem>
      <SelectItem value="fulfilled">Fulfilled</SelectItem>
    </SelectGroup>

    <SelectSeparator />

    <SelectGroup>
      <SelectLabel>Exceptions</SelectLabel>
      <SelectItem value="backordered">Backordered</SelectItem>
      <SelectItem value="blocked">Blocked</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

Small

Code

<Select>
  <SelectTrigger size="sm">
    <SelectValue placeholder="Select region" />
  </SelectTrigger>

  <SelectContent>
    <SelectItem value="north">North</SelectItem>
    <SelectItem value="south">South</SelectItem>
    <SelectItem value="west">West</SelectItem>
  </SelectContent>
</Select>

API

Select

Name	Type/Description
actionsRef	RefObject<SelectRootActions | null> | undefined A ref to imperative actions. - `unmount`: Manually unmounts the select. Call this after any externally controlled closing animation finishes.
autoComplete	string | undefined Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete
defaultOpen = false	boolean | undefined Whether the select popup is initially open. To render a controlled select popup, use the `open` prop instead.
defaultValue	SelectValueType<Value, Multiple> | null | undefined The uncontrolled value of the select when it's initially rendered. To render a controlled select, use the `value` prop instead.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
form	string | undefined Identifies the form that owns the hidden input. Useful when the select is rendered outside the form.
highlightItemOnHover = true	boolean | undefined Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
id	string | undefined The id of the Select.
inputRef	Ref<HTMLInputElement> | undefined A ref to access the hidden input element.
isItemEqualToValue	((itemValue: Value, value: Value) => boolean) | undefined 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.
items	readonly Group<any>[] | Record<string, ReactNode> | readonly { label: ReactNode; value: any; }[] | undefined 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. @example ```tsx const items = { sans: 'Sans-serif', serif: 'Serif', mono: 'Monospace', cursive: 'Cursive', }; <Select.Root items={items} /> ```
itemToStringLabel	((itemValue: Value) => string) | undefined 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.
itemToStringValue	((itemValue: Value) => string) | undefined 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.
modal = true	boolean | undefined 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.
multiple = false	boolean | undefined Whether multiple items can be selected.
name	string | undefined Identifies the field when a form is submitted.
onOpenChange	((open: boolean, eventDetails: SelectRootChangeEventDetails) => void) | undefined Event handler called when the select popup is opened or closed.
onOpenChangeComplete	((open: boolean) => void) | undefined Event handler called after any animations complete when the select popup is opened or closed.
onValueChange	((value: SelectValueType<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void) | undefined Event handler called when the value of the select changes.
open	boolean | undefined Whether the select popup is currently open.
readOnly = false	boolean | undefined Whether the user should be unable to choose a different option from the select popup.
required = false	boolean | undefined Whether the user must choose a value before submitting a form.
value	SelectValueType<Value, Multiple> | null | undefined The value of the select. Use when controlled.

SelectContent

Name	Type/Description
align = "center"	Align | undefined How to align the popup relative to the specified side.
alignItemWithTrigger = true	boolean | undefined 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.
alignOffset = 0	number | OffsetFunction | undefined 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. @example ```jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} /> ```
className	string | ((state: SelectPopupState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) | undefined 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.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPopupState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
side = "bottom"	Side | undefined Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset = 4	number | OffsetFunction | undefined 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. @example ```jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} /> ```
style	CSSProperties | ((state: SelectPopupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

SelectGroup

Name	Type/Description
className	string | ((state: SelectGroupState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: SelectGroupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

SelectItem

Name	Type/Description
className	string | ((state: SelectItemState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
label	string | undefined 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 = true	boolean | undefined 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>`).
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: SelectItemState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.
value = "null"	any A unique value that identifies this select item.

SelectLabel

Name	Type/Description
className	string | ((state: SelectGroupLabelState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupLabelState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: SelectGroupLabelState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

SelectScrollDownButton

Name	Type/Description
className	string | ((state: SelectScrollDownArrowState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
keepMounted = false	boolean | undefined Whether to keep the HTML element in the DOM while the select popup is not scrollable.
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollDownArrowState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: SelectScrollDownArrowState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

SelectScrollUpButton

Name	Type/Description
className	string | ((state: SelectScrollUpArrowState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
keepMounted = false	boolean | undefined Whether to keep the HTML element in the DOM while the select popup is not scrollable.
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollUpArrowState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: SelectScrollUpArrowState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

SelectSeparator

Name	Type/Description
className	string | ((state: SeparatorState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
orientation = "'horizontal'"	Orientation | undefined The orientation of the separator.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: SeparatorState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

SelectTrigger

Name	Type/Description
className	string | ((state: SelectTriggerState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
disabled	boolean | undefined Whether the component should ignore user interaction.
nativeButton = true	boolean | undefined 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>`).
ref	((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectTriggerState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
size = "default"	"default" | "sm" | undefined
style	CSSProperties | ((state: SelectTriggerState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

SelectValue

Name	Type/Description
children	ReactNode | ((value: any) => ReactNode) Accepts a function that returns a `ReactNode` to format the selected value. @example ```tsx <Select.Value> {(value: string | null) => value ? labels[value] : 'No value'} </Select.Value> ```
className	string | ((state: SelectValueState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
placeholder	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`.
ref	((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectValueState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: SelectValueState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.