Select
Picks one option from a short list shown in a popup under a button.
function SelectDemo() {
const severities = [
{ label: "Critical", value: "critical" },
{ label: "High", value: "high" },
{ label: "Medium", value: "medium" },
{ label: "Low", value: "low" },
]
return (
<Select items={severities}>
<SelectTrigger aria-label="Severity" className="w-44">
<SelectValue placeholder="Select severity" />
</SelectTrigger>
<SelectContent>
{severities.map((severity) => (
<SelectItem key={severity.value} value={severity.value}>
{severity.label}
</SelectItem>
))}
</SelectContent>
</Select>
)
}Usage
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@zenoxai/ui/components/select"
const severities = [
{ label: "Critical", value: "critical" },
{ label: "High", value: "high" },
]
<Select items={severities}>
<SelectTrigger aria-label="Severity">
<SelectValue placeholder="Select severity" />
</SelectTrigger>
<SelectContent>
{severities.map((severity) => (
<SelectItem key={severity.value} value={severity.value}>
{severity.label}
</SelectItem>
))}
</SelectContent>
</Select>
Pass the options to Select as items, either an array of { label, value } or an object
that maps each value to its label. SelectValue uses it to show the label of the selected
value; without items it shows the raw value (critical).
Use a select for a list of up to about 15 options that the user knows by name. For a longer list, or one the user searches, use a Combobox. For two to five options that should all stay visible, use a Radio Group. On touch-first screens, a Native Select gives the platform’s own picker.
The trigger is w-fit by default. Give it a width (w-44) so it does not resize when the
value changes, or w-full inside a Field.
Examples
With a label
Put the id on SelectTrigger and point a FieldLabel at it.
Where the tenant's events and reports are stored.
function SelectWithLabel() {
const regions = [
{ label: "Europe (Frankfurt)", value: "eu-central" },
{ label: "United States (Virginia)", value: "us-east" },
{ label: "Asia Pacific (Singapore)", value: "ap-southeast" },
]
return (
<Field className="max-w-xs">
<FieldLabel htmlFor="data-region">Data region</FieldLabel>
<Select items={regions} defaultValue="eu-central">
<SelectTrigger
id="data-region"
className="w-full"
aria-describedby="data-region-description"
>
<SelectValue />
</SelectTrigger>
<SelectContent>
{regions.map((region) => (
<SelectItem key={region.value} value={region.value}>
{region.label}
</SelectItem>
))}
</SelectContent>
</Select>
<FieldDescription id="data-region-description">
Where the tenant's events and reports are stored.
</FieldDescription>
</Field>
)
}Groups
SelectGroup with a SelectLabel names a section of options; SelectSeparator divides
sections. disabled on a SelectItem keeps it visible but not selectable.
function SelectWithGroups() {
const templates = {
soc2: "SOC 2 Type II",
iso27001: "ISO 27001",
pci: "PCI DSS",
weekly: "Weekly summary",
incident: "Incident report",
exposure: "External exposure",
}
return (
<Select items={templates} defaultValue="weekly">
<SelectTrigger aria-label="Report template" className="w-52">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectGroup>
<SelectLabel>Compliance</SelectLabel>
<SelectItem value="soc2">SOC 2 Type II</SelectItem>
<SelectItem value="iso27001">ISO 27001</SelectItem>
<SelectItem value="pci" disabled>
PCI DSS
</SelectItem>
</SelectGroup>
<SelectSeparator />
<SelectGroup>
<SelectLabel>Operations</SelectLabel>
<SelectItem value="weekly">Weekly summary</SelectItem>
<SelectItem value="incident">Incident report</SelectItem>
<SelectItem value="exposure">External exposure</SelectItem>
</SelectGroup>
</SelectContent>
</Select>
)
}Sizes
size="sm" on the trigger (28px) fits toolbars and table headers, default (32px) is the
form size and lg (36px) matches a large Input or Button. The chevron is 14px at sm and
16px otherwise. Below the md breakpoint the text is 16px, as in Input, so iOS does not zoom
the page when the trigger takes focus.
function SelectSizes() {
const statuses = [
{ label: "Open", value: "open" },
{ label: "In progress", value: "in-progress" },
{ label: "Closed", value: "closed" },
]
return (
<>
<Select items={statuses} defaultValue="open">
<SelectTrigger size="sm" aria-label="Status (small)" className="w-36">
<SelectValue />
</SelectTrigger>
<SelectContent>
{statuses.map((status) => (
<SelectItem key={status.value} value={status.value}>
{status.label}
</SelectItem>
))}
</SelectContent>
</Select>
<Select items={statuses} defaultValue="open">
<SelectTrigger aria-label="Status" className="w-36">
<SelectValue />
</SelectTrigger>
<SelectContent>
{statuses.map((status) => (
<SelectItem key={status.value} value={status.value}>
{status.label}
</SelectItem>
))}
</SelectContent>
</Select>
<Select items={statuses} defaultValue="open">
<SelectTrigger size="lg" aria-label="Status (large)" className="w-36">
<SelectValue />
</SelectTrigger>
<SelectContent>
{statuses.map((status) => (
<SelectItem key={status.value} value={status.value}>
{status.label}
</SelectItem>
))}
</SelectContent>
</Select>
</>
)
}Invalid
Set aria-invalid on SelectTrigger and data-invalid on the Field.
function SelectInvalid() {
const analysts = [
{ label: "Dana Whitfield", value: "dana" },
{ label: "Marcus Oyelaran", value: "marcus" },
{ label: "Priya Raman", value: "priya" },
]
return (
<Field data-invalid className="max-w-xs">
<FieldLabel htmlFor="incident-owner">Incident owner</FieldLabel>
<Select items={analysts}>
<SelectTrigger
id="incident-owner"
className="w-full"
aria-invalid
aria-describedby="incident-owner-error"
>
<SelectValue placeholder="Select an analyst" />
</SelectTrigger>
<SelectContent>
{analysts.map((analyst) => (
<SelectItem key={analyst.value} value={analyst.value}>
{analyst.label}
</SelectItem>
))}
</SelectContent>
</Select>
<FieldError id="incident-owner-error">
Assign an owner before escalating the incident.
</FieldError>
</Field>
)
}Controlled
Pass value and onValueChange. The value is null when nothing is selected, so type the
state as string | null.
Showing alerts from the last 7 days.
function SelectControlled() {
const ranges = [
{ label: "Last 24 hours", value: "24h" },
{ label: "Last 7 days", value: "7d" },
{ label: "Last 30 days", value: "30d" },
]
const [range, setRange] = React.useState<string | null>("7d")
const selected = ranges.find((item) => item.value === range)
return (
<div className="grid justify-items-center gap-3">
<Select items={ranges} value={range} onValueChange={setRange}>
<SelectTrigger aria-label="Time range" className="w-44">
<SelectValue />
</SelectTrigger>
<SelectContent>
{ranges.map((item) => (
<SelectItem key={item.value} value={item.value}>
{item.label}
</SelectItem>
))}
</SelectContent>
</Select>
<p className="text-sm text-text-secondary">
Showing alerts from the {selected?.label.toLowerCase()}.
</p>
</div>
)
}Accessibility
- The trigger has
role="combobox"and needs a name: aFieldLabelpointing at itsid, oraria-label. The selected value alone does not name it. - Arrow keys move through the options, typing jumps to the first option that starts with the typed text, Enter selects and Escape closes without changing the value.
- Focus returns to the trigger when the popup closes.
nameandrequiredonSelectrender a hidden input, so the value submits with a native form.
API reference
Generated from the TypeScript source. className, style and children are accepted everywhere and omitted below.
Select
Groups all parts of the select. Doesn't render its own HTML element.
| Prop | Type | Default |
|---|---|---|
actionsRef | RefObject<SelectRootActions | null>A ref to imperative actions. - `unmount`: Ends the closing phase of the select after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the select completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. - `close`: Closes the select imperatively when called. | - |
autoComplete | stringProvides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete | - |
defaultOpen | booleanWhether the select popup is initially open. | false |
defaultValue | SelectInputValue<Value, Multiple> | nullThe uncontrolled value of the select when it's initially rendered. | - |
disabled | booleanWhether the component should ignore user interaction. | false |
form | stringIdentifies the form that owns the hidden input. Useful when the select is rendered outside the form. | - |
highlightItemOnHover | booleanWhether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. | true |
id | stringThe id of the Select. | - |
inputRef | Ref<HTMLInputElement>A ref to access the hidden input element. | - |
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. | - |
items | readonly Group<any>[] | Record<string, ReactNode> | readonly { label: ReactNode; value: any; }[]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)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. | - |
modal | booleanDetermines 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. | true |
multiple | booleanWhether multiple items can be selected. | false |
name | stringIdentifies the field when a form is submitted. | - |
onOpenChange | ((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)Event handler called when the select popup is opened or closed. | - |
onOpenChangeComplete | ((open: boolean) => void)Event handler called after any animations complete when the select popup is opened or closed. | - |
onValueChange | ((value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)Event handler called when the value of the select changes. | - |
open | booleanWhether the select popup is currently open. | - |
readOnly | booleanWhether the user should be unable to choose a different option from the select popup. | false |
required | booleanWhether the user must choose a value before submitting a form. | false |
value | SelectInputValue<Value, Multiple> | nullThe value of the select. Use when controlled. | - |
SelectContent
SelectContent is the popup list, in a portal below the trigger and as wide as it, with scroll arrows when the items overflow.
| Prop | Type | Default |
|---|---|---|
align | "center" | "start" | "end"How to align the popup relative to the specified side. | start |
alignItemWithTrigger | booleanWhether the positioner overlaps the trigger so the selected item's text is aligned with the trigger's value text. This only applies to mouse input and is automatically disabled if there is not enough space. | false |
alignOffset | number | OffsetFunctionAdditional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. | 0 |
finalFocus | boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)Determines the element to focus when the select popup is closed. | - |
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPopupState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
side | "left" | "right" | "top" | "bottom" | "inline-end" | "inline-start"Which side of the anchor element to align the popup against. May automatically change to avoid collisions. | bottom |
sideOffset | number | OffsetFunctionDistance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. | 0 |
SelectGroup
| Prop | Type | Default |
|---|---|---|
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
SelectItem
SelectItem is one option, with a check mark when selected. Its children are the text shown in the list.
| Prop | Type | Default |
|---|---|---|
disabled | booleanWhether the component should ignore user interaction. | false |
label | stringSpecifies the text label to use when the item is matched during keyboard text navigation. | - |
nativeButton | booleanWhether 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>`). | true |
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
value | anyA unique value that identifies this select item. | null |
SelectLabel
SelectLabel is the heading of a SelectGroup.
| Prop | Type | Default |
|---|---|---|
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupLabelState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
SelectScrollDownButton
SelectScrollDownButton scrolls the list down on hover. SelectContent renders it already.
| Prop | Type | Default |
|---|---|---|
keepMounted | booleanWhether to keep the HTML element in the DOM while the select popup is not scrollable. | false |
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollDownArrowState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
SelectScrollUpButton
SelectScrollUpButton scrolls the list up on hover. SelectContent renders it already.
| Prop | Type | Default |
|---|---|---|
keepMounted | booleanWhether to keep the HTML element in the DOM while the select popup is not scrollable. | false |
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectScrollUpArrowState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
SelectSeparator
| Prop | Type | Default |
|---|---|---|
orientation | "horizontal" | "vertical"The orientation of the separator. | 'horizontal' |
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectSeparatorState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
SelectTrigger
SelectTrigger is the button that shows the SelectValue and opens the list.
| Prop | Type | Default |
|---|---|---|
disabled | booleanWhether the component should ignore user interaction. | - |
nativeButton | booleanWhether 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>`). | true |
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectTriggerState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |
size | "default" | "sm" | "lg"Height: `sm` 28px, `default` 32px, `lg` 36px, the heights of Input and Button. The chevron is 14px at `sm`, 16px otherwise. | default |
SelectValue
SelectValue shows the selected item in the trigger. Without `items` on the root it shows the raw value, not the item's label.
| Prop | Type | Default |
|---|---|---|
placeholder | ReactNodeThe 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`. | - |
render | ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectValueState>Allows you to replace the component's HTML element with a different tag, or compose it with another component. | - |