Select

defaultValue

string

The value of the select when initially rendered. Use when you do not need to control the state of the select.

value

string

The controlled value of the select. Should be used in conjunction with onValueChange.

onValueChange

function (value: string) => void

Event handler called when the value changes.

defaultOpen

boolean

The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.

open

boolean

The controlled open state of the dialog. Must be used in conjunction with onOpenChange.

onOpenChange

function (open: boolean) => void

Event handler called when the open state of the dialog changes.

name

string

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

disabled

boolean

When true, prevents the user from interacting with select.

required

boolean

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

placeholder

ReactNode

The content that will be rendered inside the SelectValue when no value or defaultValue is set.

onCloseAutoFocus

function (event: Event) => void

Event handler called when focus moves back after closing. It can be prevented by calling event.preventDefault.

onEscapeKeyDown

function (event: KeyboardEvent) => void

Event handler called when the escape key is down. It can be prevented by calling event.preventDefault

onPointerDownOutside

function (event: PointerDownOutsideEvent) => void

Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.

position

enum ("item-aligned" | "popper")

The positioning mode to use, item-aligned is the default and behaves similarly to a native MacOS menu by positioning content relative to the active item. popper positions content in the same way as our other primitives, for example Popover or DropdownMenu.

side

enum

bottom ("top" | "right" | "bottom" | "left")

The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled.

sideOffset

number

0

The distance in pixels from the trigger.

align

enum

center ("start" | "center" | "end")

The distance in pixels from the trigger.

alignOffset

number

0

The vertical distance in pixels from the anchor.

avoidCollisions

boolean

true

When true, overrides the side andalign preferences to prevent collisions with boundary edges.

collisionBoundary

Boundary (Element | null | Array<Element | null>)

[]

The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check.

collisionPadding

number | Padding number | Partial<Record<Side, number>>

0

The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }.

sticky

enum "partial" | "always"

"partial"

The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }.

hideWhenDetached

boolean

false

Whether to hide the content when the trigger becomes fully occluded.

value*

string

The value given as data when submitted with a name.

disabled

boolean

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

textValue

string

Optional text used for typeahead purposes. Use this when the content is complex, or you have non-textual content inside.