Select
Choose one item from a non-editable collection.
Anatomy#
Select renders the portaled popup internally; the popup names are style slots, not attached parts. Use BaseSelect to compose the listbox yourself.
Usage#
Use Select for one choice from a non-editable collection. Use Combobox when users need to type a query or the collection is large enough to need virtualization, MultiSelect for several collection values, or BaseSelect to compose the listbox yourself.
String items#
Pass strings when the label and value are identical. You can mix strings and objects at the root or inside a group. Whitespace is preserved, and an empty string is a valid value.
A string item normalizes to { value, label } with both set to the string, so 'Apple' becomes
{ value: 'Apple', label: 'Apple' }. Object items keep their custom fields, and
SelectT.NormalizedItem<TItem> is the item type passed to callbacks. Item values must be unique
across the collection. When two items share a value, the first one wins (including a string that
collides with an object), and development builds log an error.
Value and collection#
The value slot shows the selected label, or String(value) when the value matches no item.
Pair value with onValueChange for controlled selection, or use defaultValue for an initial
uncontrolled choice. value={undefined} keeps the selection uncontrolled; value={null} keeps it
controlled and empty. onValueChange receives null when the selection is cleared, and inside a
form field, clearing writes null.
Clear and loading#
clearable shows a clear button beside the trigger while a value is selected. Clicking it clears
the selection without toggling the popup. Backspace or Delete on the focused trigger also clears.
Clearing calls onValueChange(null), then onClear, and returns focus to the trigger. Neither
fires while the select is disabled or read-only.
loading swaps the trailing icon for loadingIcon and hides the clear button. It does not
disable the select.
Popup positioning and dismissal#
The popup opens below the control and aligns to its start edge. placement, align, gutter,
shift, flip, slide, and overflowPadding adjust that position. closeOnEscape and
closeOnOutsideClick default to true; set either to false to block that dismissal and listen
for it with onClosePrevented. Combobox and MultiSelect accept the same props. open,
defaultOpen, and onOpenChange control the popup state.
Keyboard interaction#
| Key | Behavior |
|---|---|
| Enter / Space | Open the popup, or commit the highlighted option while open |
| ArrowDown / ArrowUp | Open the popup and move the highlight through enabled options |
| Home / End | Highlight the first or last enabled option while open |
| PageUp / PageDown | Move the highlight by one page of options while open |
| Printable key | Typeahead: highlight the matching label while open, select it if closed |
| Backspace / Delete | Clear the value when clearable and a value is selected |
| Escape | Close the popup without changing the value |
| Tab | Close the popup and move focus on |
Examples#
Choose a subscription plan#
Put an icon and description on each item when the choice needs more than a label. No custom
item template is required.
Assign a member role#
Pick one permission role from a short collection. Keep the selected value as the role id.
Choose a workspace timezone#
Organize options with type: 'group'. Insert { type: 'separator' } between groups or items.
Group labels and separators are excluded from selection and keyboard navigation.
Load more options on scroll#
Use onBottomReached and scrollThreshold to append pages as the listbox approaches the
bottom. Drive loading from the in-flight request.
Bind an empty select to a form#
For an empty form.Field-bound Select, initialize the field with null and accept null in the
schema. required is satisfied by any selected value, including one whose item is disabled. In that
case the select passes constraint validation but submits no value, as a native <select> does with
a disabled selected option.
Own the selected country code#
Pair value with onValueChange. Clearing writes null. Nearby copy can read the same signal.
Accept string labels or mixed items#
Pass a string array when the label is the value. Mix strings, item objects, and type: 'group'
entries in one items list.
Custom option and empty state renderers#
Use itemRender to customize row content with badges or status details. Use emptyRender to
render a message or recovery action when items is empty.
API Reference#
Attributes#
data-closeddata-disableddata-expandeddata-invaliddata-readonlydata-requireddata-sidedata-highlighteddata-selecteddata-loadingdata-placeholderProps#
Renders a <div> element by default.