# Select

A dropdown that picks one value, or several with `multiple`, from a list of `items`. Keyboard navigation and typeahead; values can be any type and compare with `Object.is`. Inside a `Field` the trigger takes the field id, label, disabled, required, invalid and message wiring. Each part is also exported on its own, such as `SelectTrigger`.

## Use for

- picking one option from a list, such as a role
- picking several options from a list
- a compact dropdown in a table row
- options with an icon, avatar or description

## Practices

- Do: Pass every choice as `items` on the root, so the closed trigger can show the selected label.
- Do: Use `variant='ghost'` and an `aria-label` for a trigger in a table row.
- Do: Wrap it in `Field.Root` with a `Field.Label` in a form, instead of labelling the trigger by hand.
- Don't: Use it when the user types to filter options. Use `Combobox` instead.

## API reference

### Select.Root

Holds the selection and the items. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `SelectItem<Value>[]` |  | `{ value, label, description?, disabled? }` for every choice. `label` drives typeahead. |
| `multiple` | `boolean` | `false` | Makes the value an array. Picking an option toggles it and keeps the popup open. |
| `value` | `Value \| Value[] \| null` |  | The selection, when controlled. An array with `multiple`. |
| `defaultValue` | `Value \| Value[] \| null` |  | The selection on mount, when uncontrolled. |
| `onValueChange` | `((value: Value) => void) \| ((value: Value[]) => void)` |  | Called with the new selection. |
| `open` | `boolean` |  | Open state, when controlled. |
| `defaultOpen` | `boolean` | `false` | Open state on mount. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state. |
| `alignItemWithTrigger` | `boolean` | ``true, or false when `multiple` or any item has a description`` | Overlays the selected option on the trigger, like a native `select`. Falls back below the trigger on touch or near an edge. |
| `placement` | `'top' \| 'right' \| 'bottom' \| 'left' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end'` | `'bottom-start'` | Side and alignment when not aligned with the trigger. |
| `sideOffset` | `number` | `4` | Gap in px between trigger and popup. |

### Select.Trigger

Opens the listbox and shows the selected label, with a chevron (`cl-select-trigger-icon`). Renders a neutral `md` `Button`, or the `render` element. Carries `data-variant`, and `data-open` or `data-closed`.

Slot: `cl-select-trigger`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `SelectTriggerVariant` | `'outline'` | `outline` for a form control, `ghost` for a dense surface such as a table row. |
| `placeholder` | `React.ReactNode` |  | Shown while nothing is selected. |
| `children` | `React.ReactNode \| ((value: unknown[]) => React.ReactNode)` |  | A function receives the selected values and renders inside the value slot (`cl-select-value`); anything else replaces it. |

### Select.Popup

The floating `role='listbox'`, with a scrolling viewport (`cl-select-viewport`) in a positioner (`cl-select-positioner`). Renders one `Select.Option` per item unless given children.

Slot: `cl-select-popup`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `portalRoot` | `SelectPortalProps['root']` | `document.body` | Container the listbox portals into. |

### Select.Option

One `role='option'` with a check (`cl-select-option-indicator`) when selected. Carries `data-selected`, `data-active`, `data-disabled`, and `data-described` when it has a description.

Slot: `cl-select-option`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `unknown` |  | The value this option selects. |
| `label` | `string` |  | Shown in the row and the trigger; drives typeahead. |
| `description` | `string` |  | A secondary line under the label. |
| `disabled` | `boolean` |  | Keeps the option focusable but not selectable. |
| `children` | `React.ReactNode` |  | Composes the row from `Select.Media` and `Select.Content`. Without it the row shows `label` and `description`. |

### Select.Media

A square leading column for an icon, image or avatar.

Slot: `cl-select-option-media`

### Select.Content

Stacks the label and description beside the media.

Slot: `cl-select-option-content`

### Select.Label

The option's name, on one line. Names the option.

Slot: `cl-select-option-label`

### Select.Description

A secondary line under the label. Describes the option without joining its name.

Slot: `cl-select-option-description`

## Examples

### In a field

```tsx
<Field.Root>
  <Field.Label>Role</Field.Label>
  <Select.Root items={roles} value={role} onValueChange={setRole}>
    <Select.Trigger placeholder={m.rolePlaceholder} />
    <Select.Popup />
  </Select.Root>
</Field.Root>
```

### In a table row

```tsx
<Select.Root items={roles} value={member.role} onValueChange={onChangeRole}>
  <Select.Trigger variant='ghost' aria-label={label} />
  <Select.Popup />
</Select.Root>
```

## Related

- [Field](/docs/components/field.md)
- [Combobox](/docs/components/combobox.md)
