Skip to content
UI

Select

Picks one option from a short list shown in a popup under a button.

@zenoxai/ui/components/selectBase UI Markdown
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: a FieldLabel pointing at its id, or aria-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.
  • name and required on Select render 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.

PropTypeDefault
actionsRefRefObject<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.

-
autoCompletestring

Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete

-
defaultOpenboolean

Whether the select popup is initially open.

false
defaultValueSelectInputValue<Value, Multiple> | null

The uncontrolled value of the select when it's initially rendered.

-
disabledboolean

Whether the component should ignore user interaction.

false
formstring

Identifies the form that owns the hidden input. Useful when the select is rendered outside the form.

-
highlightItemOnHoverboolean

Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.

true
idstring

The id of the Select.

-
inputRefRef<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.

-
itemsreadonly 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.

-
modalboolean

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.

true
multipleboolean

Whether multiple items can be selected.

false
namestring

Identifies 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.

-
openboolean

Whether the select popup is currently open.

-
readOnlyboolean

Whether the user should be unable to choose a different option from the select popup.

false
requiredboolean

Whether the user must choose a value before submitting a form.

false
valueSelectInputValue<Value, Multiple> | null

The 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.

PropTypeDefault
align"center" | "start" | "end"

How to align the popup relative to the specified side.

start
alignItemWithTriggerboolean

Whether 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
alignOffsetnumber | OffsetFunction

Additional 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
finalFocusboolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)

Determines the element to focus when the select popup is closed.

-
renderReactElement<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
sideOffsetnumber | OffsetFunction

Distance 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

PropTypeDefault
renderReactElement<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.

PropTypeDefault
disabledboolean

Whether the component should ignore user interaction.

false
labelstring

Specifies the text label to use when the item is matched during keyboard text navigation.

-
nativeButtonboolean

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>`).

true
renderReactElement<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.

-
valueany

A unique value that identifies this select item.

null

SelectLabel

SelectLabel is the heading of a SelectGroup.

PropTypeDefault
renderReactElement<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.

PropTypeDefault
keepMountedboolean

Whether to keep the HTML element in the DOM while the select popup is not scrollable.

false
renderReactElement<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.

PropTypeDefault
keepMountedboolean

Whether to keep the HTML element in the DOM while the select popup is not scrollable.

false
renderReactElement<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

PropTypeDefault
orientation"horizontal" | "vertical"

The orientation of the separator.

'horizontal'
renderReactElement<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.

PropTypeDefault
disabledboolean

Whether the component should ignore user interaction.

-
nativeButtonboolean

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>`).

true
renderReactElement<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.

PropTypeDefault
placeholderReactNode

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`.

-
renderReactElement<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.

-