//
Displays a list of options for the user to pick from.
bun add xiod-ui1import {2 Select,3 SelectButton,4 SelectContent,5 SelectPopup,6 SelectGroup,7 SelectGroupLabel,8 SelectItem,9 SelectSeparator,10 SelectTrigger,11 SelectValue12} from "xiod-ui/select";1<Select>2 <SelectTrigger />3 <SelectContent>4 <SelectGroupLabel />5 <SelectGroup>6 <SelectItem />7 </SelectGroup>8 <SelectButton />9 <SelectPopup />10 <SelectSeparator />11 <SelectValue />12 </SelectContent>13</Select>| Prop | Type | Default | Description |
|---|---|---|---|
inputRef | Ref<HTMLInputElement>| undefined | - | A ref to access the hidden input element. |
name | string| undefined | - | Identifies the field when a form is submitted. |
form | string| undefined | - | Identifies the form that owns the hidden input. Useful when the select is rendered outside the form. |
autoComplete | string| undefined | - | Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete |
id | string| undefined | - | The id of the Select. |
required | boolean| undefined | false | Whether the user must choose a value before submitting a form. |
readOnly | boolean| undefined | false | Whether the user should be unable to choose a different option from the select popup. |
disabled | boolean| undefined | false | Whether the component should ignore user interaction. |
multiple | boolean| undefined | false | Whether multiple items can be selected. |
highlightItemOnHover | boolean| undefined | 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. |
defaultOpen | boolean| undefined | false | Whether the select popup is initially open. To render a controlled select popup, use the `open` prop instead. |
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. |
open | boolean| undefined | - | Whether the select popup is currently open. |
modal | boolean| undefined | 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. |
actionsRef | RefObject<SelectRootActions| null>| undefined | - | A ref to imperative actions. - `unmount`: Manually unmounts the select. Call this after any externally controlled closing animation finishes. |
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. |
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. |
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. |
value | SelectValueType<Value, Multiple>| null| undefined | - | The value of the select. Use when controlled. |
onValueChange | ((value: SelectValueType<Value, Multiple>| (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)| undefined | - | Event handler called when the value of the select changes. |
| Prop | Type | Default | Description |
|---|---|---|---|
size | "default"| "sm"| "lg"| null| undefined | default | |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, {}>| 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. |
| Prop | Type | Default | Description |
|---|---|---|---|
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. |
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. |
render | ReactElement<unknown, 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. |
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. |
side | Side| undefined | bottom | |
sideOffset | number| OffsetFunction| undefined | 4 | |
align | Align| undefined | start | |
alignOffset | number| OffsetFunction| undefined | 0 | |
alignItemWithTrigger | boolean| undefined | true | |
anchor | Element| VirtualElement| RefObject<Element| null>| (() => Element| VirtualElement| null)| null| undefined | - |
| Prop | Type | Default | 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. |
render | ReactElement<unknown, 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. |
| Prop | Type | Default | 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. |
render | ReactElement<unknown, 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. |
| Prop | Type | Default | Description |
|---|---|---|---|
value | any | null | A unique value that identifies this select item. |
disabled | boolean| undefined | false | 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 | boolean| undefined | true | 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>`). |
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. |
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. |
render | ReactElement<unknown, 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. |
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | Orientation| undefined | 'horizontal' | The orientation of the separator. |
className | string| ((state: SelectSeparatorState) => string| undefined)| undefined | - | CSS class applied to the element, or a function that returns a class based on the component's state. |
render | ReactElement<unknown, string| JSXElementConstructor<any>>| ComponentRenderFn<HTMLProps, SelectSeparatorState>| 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: SelectSeparatorState) => CSSProperties| undefined)| undefined | - | Style applied to the element, or a function that returns a style object based on the component's state. |
| Prop | Type | Default | Description |
|---|---|---|---|
disabled | boolean| undefined | - | Whether the component should ignore user interaction. |
nativeButton | boolean| undefined | true | 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>`). |
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. |
render | ReactElement<unknown, 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. |
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. |
size | "default"| "sm"| "lg"| null| undefined | default |
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode| ((value: any) => 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. @example ```tsx <Select.Value> {(value: string | null) => value ? labels[value] : 'No value'} </Select.Value> ``` |
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`. |
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. |
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. |
render | ReactElement<unknown, 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. |