Select
One value picked from a list and held on the trigger: the input's field over the menu's popup and rows, opening with the chosen row level with the value.
01Preview
0102Installation
npx shadcn@latest add https://aiellie.app/r/select.json03API reference
19From the Base UI documentation
Groups all parts of the select. Doesn't render its own HTML element.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | - | Identifies the field when a form is submitted. |
| defaultValue | Value[] | Value | null | - | The uncontrolled value of the select when it's initially rendered. To render a controlled select, use the value prop instead. |
| value | Value[] | Value | null | - | The value of the select. Use when controlled. |
| onValueChange | ((value: Value[] | Value | null, eventDetails: Select.Root.ChangeEventDetails) => void) | - | Event handler called when the value of the select changes. |
| defaultOpen | boolean | false | Whether the select popup is initially open. To render a controlled select popup, use the open prop instead. |
| open | boolean | - | Whether the select popup is currently open. |
| onOpenChange | ((open: boolean, eventDetails: Select.Root.ChangeEventDetails) => void) | - | Event handler called when the select popup is opened or closed. |
| highlightItemOnHover | boolean | true | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state. |
| actionsRef | React.RefObject<Select.Root.Actions | null> | - | A ref to imperative actions. unmount: Manually unmounts the select. Call this after any externally controlled closing animation finishes. |
| autoComplete | string | - | Provides a hint to the browser for autofill. |
| form | string | - | Identifies the form that owns the hidden input. Useful when the select is rendered outside the form. |
| 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. |
| 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. |
| 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. |
| items | Record<string, React.ReactNode> | ({ label: React.ReactNode; value: any })[] | Group[] | - | 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. |
| modal | boolean | true | 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. |
| multiple | boolean | false | Whether multiple items can be selected. |
| onOpenChangeComplete | ((open: boolean) => void) | - | Event handler called after any animations complete when the select popup is opened or closed. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| readOnly | boolean | false | Whether the user should be unable to choose a different option from the select popup. |
| required | boolean | false | Whether the user must choose a value before submitting a form. |
| inputRef | React.Ref<HTMLInputElement> | - | A ref to access the hidden input element. |
| id | string | - | The id of the Select. |
| children | React.ReactNode | - | - |