Select
Displays a list of options for the user to pick from—triggered by a button.
Examples
Default
Preview
Floating Label
Preview
With Groups
Preview
Disabled
Preview
Invalid
Preview
This field is required
With Helper Text
Preview
Choose an option from the list
Medium size (md)
Preview
With Icons
Preview
API
Root
Contains all the parts of a select.
| Property | Type | Default | Description |
|---|---|---|---|
| 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 | (value: string) => void | - | Event handler called when the value changes. |
| defaultOpen | boolean | false | The open state of the select when it is initially rendered. |
| open | boolean | - | The controlled open state of the select. |
| onOpenChange | (open: boolean) => void | - | Event handler called when the open state of the select changes. |
| disabled | boolean | false | When true, prevents the user from interacting with the select. |
| name | string | - | The name of the select. Submitted with its owning form as part of a name/value pair. |
| required | boolean | false | When true, indicates that the user must select a value before the owning form can be submitted. |
| invalid | boolean | false | When true, enables error state styling for the trigger and helper text (SelectText). |
| size | ”md” | “lg" | "lg” | The size variant of the select trigger. Affects height, font size, and icon scale. |
Trigger
The button that toggles the select.
| Property | Type | Default | Description |
|---|---|---|---|
| asChild | boolean | false | Change the default rendered element for the one passed as a child, merging their props and behavior. |
| className | string | - | Additional CSS classes to apply to the trigger. |
Value
The part that reflects the selected value.
| Property | Type | Default | Description |
|---|---|---|---|
| placeholder | ReactNode | - | The content that will be rendered inside the SelectValue when no value or defaultValue is set. |
Content
The component that pops out when the select is open.
| Property | Type | Default | Description |
|---|---|---|---|
| position | ”item-aligned” | “popper" | "popper” | The positioning mode to use. “item-aligned” aligns the content to the trigger, “popper” positions like a typical dropdown. |
| side | ”top” | “right” | “bottom” | “left" | "bottom” | The preferred side of the trigger to render against when open. Will be reversed when collisions occur. |
| sideOffset | number | 0 | The distance in pixels from the trigger. |
| align | ”start” | “center” | “end" | "start” | The preferred alignment against the trigger. May change when collisions occur. |
| className | string | - | Additional CSS classes to apply to the content. |
Item
The component that contains the select items.
| Property | Type | Default | Description |
|---|---|---|---|
| value | string | - | The value given as data when submitted with a name. Required. |
| disabled | boolean | false | When true, prevents the user from interacting with the item. |
| textValue | string | - | Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the SelectItemText part. |
| icon | ReactNode | - | An icon element to be rendered on the left of the item text. |
| className | string | - | Additional CSS classes to apply to the item. |
Group
Used to group multiple items.
| Property | Type | Default | Description |
|---|---|---|---|
| asChild | boolean | false | Change the default rendered element for the one passed as a child, merging their props and behavior. |
Header
Used to render the header of a group. It won’t be focusable using arrow keys.
| Property | Type | Default | Description |
|---|---|---|---|
| asChild | boolean | false | Change the default rendered element for the one passed as a child, merging their props and behavior. |
| className | string | - | Additional CSS classes to apply to the label. |
Separator
Used to visually separate items in the select.
| Property | Type | Default | Description |
|---|---|---|---|
| asChild | boolean | false | Change the default rendered element for the one passed as a child, merging their props and behavior. |
| className | string | - | Additional CSS classes to apply to the separator. |
Wrapper
Container component required for floating label functionality and helper text. It tracks the select state and enables the label animation.
| Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional CSS classes to apply to the wrapper. |
| children | ReactNode | - | Should contain the Select component and SelectLabel. |
Label
Floating label component that animates when the select is focused or has a value. Must be used inside a SelectWrapper.
| Property | Type | Default | Description |
|---|---|---|---|
| htmlFor | string | - | The id of the select trigger the label is associated with. |
| className | string | - | Additional CSS classes to apply to the label. |
Text
Helper text component that displays information below the select trigger. Can show error messages or general helper text. Automatically detects error state based on the invalid prop of the Select component.
| Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional CSS classes to apply to the text. |
| children | ReactNode | - | The text content to display. Automatically styled as error text (feedback-error-foreground) when Select has invalid={true}, otherwise displays in normal color (gray-foreground). |
Last updated on