# Select

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

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@zenoxai/ui/components/select"

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

```tsx
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](/components/combobox). For two to five
options that should all stay visible, use a [Radio Group](/components/radio-group). On
touch-first screens, a [Native Select](/components/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](/components/field).

## Examples

### With a label

Put the `id` on `SelectTrigger` and point a `FieldLabel` at it.

```tsx
import { Field, FieldDescription, FieldLabel } from "@zenoxai/ui/components/field"
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@zenoxai/ui/components/select"

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.

```tsx
import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue } from "@zenoxai/ui/components/select"

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.

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@zenoxai/ui/components/select"

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

```tsx
import { Field, FieldError, FieldLabel } from "@zenoxai/ui/components/field"
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@zenoxai/ui/components/select"

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

```tsx
import * as React from "react"
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@zenoxai/ui/components/select"

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

`import { ... } from "@zenoxai/ui/components/select"`

### Select

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| 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 | `string` |  | Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete |
| defaultOpen | `boolean` | `false` | Whether the select popup is initially open.  To render a controlled select popup, use the `open` prop instead. |
| defaultValue | `SelectInputValue<Value, Multiple> \| null` |  | The uncontrolled value of the select when it's initially rendered.  To render a controlled select, use the `value` prop instead. |
| disabled | `boolean` | `false` | Whether the component should ignore user interaction. |
| form | `string` |  | Identifies the form that owns the hidden input. Useful when the select is rendered outside the form. |
| 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. |
| id | `string` |  | The 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 | `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. |
| name | `string` |  | 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. |
| open | `boolean` |  | Whether the select popup is currently open. |
| 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. |
| value | `SelectInputValue<Value, Multiple> \| null` |  | The value of the select. Use when controlled. |

### SelectContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | `"center" \| "start" \| "end"` | `start` | How to align the popup relative to the specified side. |
| alignItemWithTrigger | `boolean` | `false` | 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. |
| alignOffset | `number \| OffsetFunction` | `0` | 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.  The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner   alignOffset={({ side, align, anchor, positioner }) => {     return side === 'top' \|\| side === 'bottom'       ? anchor.width       : anchor.height;   }} /> ``` |
| finalFocus | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` |  | 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. |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |
| side | `"left" \| "right" \| "top" \| "bottom" \| "inline-end" \| "inline-start"` | `bottom` | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. |
| sideOffset | `number \| OffsetFunction` | `0` | 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.  The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner   sideOffset={({ side, align, anchor, positioner }) => {     return side === 'top' \|\| side === 'bottom'       ? anchor.height       : anchor.width;   }} /> ``` |

### SelectGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |

### SelectItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | `boolean` | `false` | Whether the component should ignore user interaction. |
| label | `string` |  | 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` | `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>`). |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |
| value | `any` | `null` | A unique value that identifies this select item. |

### SelectLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |

### SelectScrollDownButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| keepMounted | `boolean` | `false` | Whether to keep the HTML element in the DOM while the select popup is not scrollable. |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |

### SelectScrollUpButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| keepMounted | `boolean` | `false` | Whether to keep the HTML element in the DOM while the select popup is not scrollable. |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |

### SelectSeparator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| orientation | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |

### SelectTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | `boolean` |  | Whether the component should ignore user interaction. |
| nativeButton | `boolean` | `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>`). |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |
| size | `"default" \| "sm" \| "lg"` | `default` | Height: `sm` 28px, `default` 32px, `lg` 36px, the heights of Input and Button. The chevron is 14px at `sm`, 16px otherwise. |

### SelectValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| 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`. |
| 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.  Accepts a `ReactElement` or a function that returns the element to render. |