# Select

> A field that opens a list of values and shows the one chosen, for picking one of up to 10 values or a few of several.

Source: https://raft-design.botiverse.build/components/select. Generated from the current release; where it differs from what you remember, this page is right.

A select is a field at the control height with an ink border, like an input: 44px on a phone, 32px on a desktop. Clicking it opens a list of values; the current value has a check mark. Use it to store a value. When choosing starts an action instead, use a menu.

## When to use

The full choice between pickers is in [Choosing a component](https://raft-design.botiverse.build/components.md#picking-something).

| Situation                                             | Use                                                                                            |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| One of up to 10 values                                | Select                                                                                         |
| A few of several values                               | Select with `multiple`                                                                         |
| One or a few of many values, with search              | [ComboboxSelect](https://raft-design.botiverse.build/components/combobox-select.md) or [Combobox](https://raft-design.botiverse.build/components/combobox.md) |
| One of 2 to 5 answers, each worth a sentence          | [RadioGroup](https://raft-design.botiverse.build/components/radio-group.md)                                                    |
| Choosing starts an action rather than storing a value | [DropdownMenu](https://raft-design.botiverse.build/components/dropdown-menu.md)                                              |
| Filtering a list                                      | Select or Combobox opened from a filter; see [Filters](#filters)                               |

## Anatomy

- `Select`: the root. Holds the value and the open state. Required.
- `SelectTrigger`: the field that opens the list. Required.
- `SelectValue`: the chosen value in the trigger, or the placeholder.
- `SelectIcon`: the chevron at the trigger's end.
- `SelectContent`: the list's popup, positioned next to the trigger. Required.
- `SelectList`: the scrolling list of items.
- `SelectItem`: one value, with `SelectItemText` and `SelectItemIndicator` (the check mark). `SelectItemLeading` holds an icon or avatar before the text. `SelectItemDescription` is an optional second line under the text.
- `SelectGroup` and `SelectGroupLabel`: a group of values under a small heading. `SelectSeparator` is a hairline between groups.
- `SelectLabel`: a label for the select when it is not in a [Field](https://raft-design.botiverse.build/components/field.md).
- `SelectScrollUpArrow`, `SelectScrollDownArrow`, `SelectPortal`, `SelectPopup`: lower-level parts for custom popups.

## Variants

| Variant            | Use for                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `chrome="default"` | A select outside a form, such as in a settings row or a toolbar                                         |
| `chrome="field"`   | A select in a form, beside inputs: its value and options use the field's type, so they match the inputs |
| `multiple`         | A few of several values                                                                                 |

### Filters

A filter is a Select or a [Combobox](https://raft-design.botiverse.build/components/combobox.md) opened from a [PickerTriggerButton](https://raft-design.botiverse.build/components/picker-trigger-button.md) above a list.

```tsx
import { ArrowDownUp, ChevronDown } from "lucide-react";
import {
  PickerTriggerButton,
  Select,
  SelectContent,
  SelectIcon,
  SelectItem,
  SelectItemIndicator,
  SelectItemText,
  SelectList,
  SelectTrigger,
  SelectValue,
} from "@botiverse/raft-ui";

const SORT_OPTIONS = [
  { value: "relevance", label: "Relevance" },
  { value: "recent", label: "Most recent" },
  { value: "comments", label: "Most commented" },
] as const;

export function PickerTriggerButtonSelectFilterComposition() {
  return (
    <Select defaultValue="relevance" items={SORT_OPTIONS} modal={false}>
      <SelectTrigger render={<PickerTriggerButton />}>
        <ArrowDownUp aria-hidden className="size-3.5" />
        <SelectValue />
        <SelectIcon>
          <ChevronDown aria-hidden className="size-3" />
        </SelectIcon>
      </SelectTrigger>
      <SelectContent className="w-[180px]">
        <SelectList>
          {SORT_OPTIONS.map((option) => (
            <SelectItem key={option.value} value={option.value}>
              <SelectItemText>{option.label}</SelectItemText>
              <SelectItemIndicator />
            </SelectItem>
          ))}
        </SelectList>
      </SelectContent>
    </Select>
  );
}
```

- Make a filter 32px high, with a 44px hit area.
- Outline a filter that is not applied with `line-seam`. Fill an applied filter with `info-soft` and show how many values it has.
- Put a `ghost` Clear All button after the filters.
- Open the same list as any picker: single or multiple, with search when there are many values.

## States

- **No value:** `SelectValue` shows the placeholder in `foreground-hint`.
- **Invalid:** `data-invalid` on the trigger gives it a `danger-strong` border.
- The trigger is a field, so it doesn't hover; a press lays the medium tier ([Hover and press](https://raft-design.botiverse.build/foundations/states.md#hover-and-press)).
- **Disabled** and the hover highlight in the list follow [States](https://raft-design.botiverse.build/foundations/states.md).

## Behavior

- Make the list as wide as the field, at least 220px. A longer option widens it up to 24rem, never past the screen less 8px on each side, and then wraps to two lines and truncates ([Forms](https://raft-design.botiverse.build/patterns/forms.md#long-values-in-fields)).
- The selected value in the trigger stays on one line and truncates; its whole text is the `title` while it is cut off.
- Align a filter's list with the filter's left edge, and with its right edge when there is no room. How every popup is positioned is in [Elevation](https://raft-design.botiverse.build/foundations/elevation.md#popups).
- Open the same list on a phone. Don't replace it with a bottom sheet: a bottom sheet is for going somewhere ([Choosing a component](https://raft-design.botiverse.build/components.md#overlays)).
- With `multiple`, keep the list open when a value is chosen. Clicking outside or Esc closes it.
- With `multiple`, put a box before each item (`CheckboxIndicator` in `SelectItemLeading`), ink when chosen ([Checkbox](https://raft-design.botiverse.build/components/checkbox.md)). The trigger shows the chosen values, or a count (3 selected) when they don't fit.

## Content

- Group values by kind (Agents, People) with `SelectGroupLabel`.
- Put secondary information (a runtime, a role, presence) at the end of the item, in `foreground-hint`.
- Put a short explanation of what a value means (what a model is good at, what a level does) on a second line, in `SelectItemDescription`. Don't repeat the label in another form, such as its id in lowercase: a line that says nothing new only makes the list taller.

```tsx
import { useState } from "react";
import {
  Select,
  SelectContent,
  SelectIcon,
  SelectItem,
  SelectItemDescription,
  SelectItemIndicator,
  SelectItemText,
  SelectList,
  SelectTrigger,
  SelectValue,
} from "@botiverse/raft-ui";

const MODELS = [
  { value: "opus", label: "Claude Opus 5.5", description: "Best for long, careful work" },
  { value: "sonnet", label: "Claude Sonnet 5.5", description: "Fast and capable for most tasks" },
  { value: "haiku", label: "Claude Haiku 5.5", description: "Quickest, for short replies" },
] as const;

const ITEMS = MODELS.map(({ value, label }) => ({ value, label }));

export function SelectDescriptionsContent() {
  const [value, setValue] = useState<string | null>("sonnet");

  return (
    <div className="w-80">
      <Select items={ITEMS} value={value} onValueChange={setValue}>
        <SelectTrigger aria-label="Model">
          <SelectValue />
          <SelectIcon />
        </SelectTrigger>
        <SelectContent>
          <SelectList>
            {MODELS.map((model) => (
              <SelectItem key={model.value} value={model.value}>
                <SelectItemText>{model.label}</SelectItemText>
                <SelectItemDescription>{model.description}</SelectItemDescription>
                <SelectItemIndicator />
              </SelectItem>
            ))}
          </SelectList>
        </SelectContent>
      </Select>
    </div>
  );
}
```

An item is as tall as its content, and its padding is constant ([Forms](https://raft-design.botiverse.build/patterns/forms.md#option-height)): one line is 36px, and a wrapped label or a description adds only its own height, with the one-line item's space above and below the text. `SelectItemDescription` sits beside `SelectItemText`, not inside it, so the trigger shows only the label. With a `SelectItemLeading`, the description starts under the label, past the icon.

- Put the empty choice first when there is one, as with Unassigned ([Tasks](https://raft-design.botiverse.build/patterns/tasks.md#filters)).

## Accessibility

Select wraps Base UI Select: a button that opens a listbox, with typeahead and arrow-key navigation.

- Name the select with a `FieldLabel` ([Field](https://raft-design.botiverse.build/components/field.md)), a `SelectLabel`, or `aria-label` on the trigger.
- In a multi-select, the box before each item is decorative; Base UI states the selection with `aria-selected`.
- `SelectItemDescription` is the option's accessible description: the item is named by `SelectItemText` alone and points `aria-describedby` at the description, so a screen reader reads the label, then the description, each once.

## API

### Select

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chrome` | `SelectChrome` | `"default"` | `field` opts this Select into the field metric axis, so it reads as a form field rather than a button. Defaults to `default`, leaving every existing Select untouched. |
| `actionsRef` | `RefObject<SelectRootActions \| null>` |  | A ref to imperative actions. - `unmount`: Manually unmounts the select. Call this after any externally controlled closing animation finishes. |
| `autoComplete` | `string` |  | Provides a hint to the browser for autofill. |
| `children` | `ReactNode` |  |  |
| `defaultOpen` | `boolean` | `false` | Whether the select popup is initially open. |
| `defaultValue` | `NonNullable<Multiple extends true ? Value[] : Value>` |  | The uncontrolled value of the select when it's initially rendered. |
| `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` | `((instance: HTMLInputElement \| null) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; }) \| DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) \| RefObject<HTMLInputElement \| null>` |  | 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: React.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. |
| `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. |
| `multiple` | `NonNullable<Multiple>` | `false` | Whether multiple items can be selected. |
| `name` | `string` |  | Identifies the field when a form is submitted. |
| `onOpenChange` | `(open: boolean, eventDetails: SelectRootChangeEventDetails) => 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: (Multiple extends true ? Value[] : Value) \| (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` | `NonNullable<Multiple extends true ? Value[] : Value>` |  | The value of the select. Use when controlled. |

### SelectArrow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `portalProps` | `SelectPortalProps` |  |  |
| `align` | `Align` | `"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. |
| `anchor` | `Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null)` |  | An element to position the popup against. By default, the popup will be positioned against the trigger. |
| `arrowPadding` | `number` | `5` | Minimum distance to maintain between the arrow and the edges of the popup. |
| `children` | `ReactNode` |  |  |
| `collisionAvoidance` | `CollisionAvoidance` |  | Determines how to handle collisions when positioning the popup. |
| `collisionBoundary` | `Boundary` | `'clipping-ancestors'` | An element or a rectangle that delimits the area that the popup is confined to. |
| `collisionPadding` | `Padding` | `8` | Additional space to maintain from the edge of the collision boundary. |
| `disableAnchorTracking` | `boolean` | `false` | Whether to disable the popup from tracking any layout shift of its positioning anchor. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void)` |  | Determines the element to focus when the select popup is closed. |
| `positionMethod` | `"fixed" \| "absolute"` | `"fixed"` | Determines which CSS `position` property to use. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `side` | `Side` | `"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. |
| `sticky` | `boolean` | `false` | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. |

Also takes the attributes of its element.

### SelectGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectGroupLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectIcon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `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. |
| `nativeButton` | `boolean` | `false` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `value` | `any` | `null` | A unique value that identifies this select item. |

Also takes the attributes of its element.

### SelectItemDescription

A second line under an option's label: what it means, not its name again. It sits beside `SelectItemText`, not inside it, so the selected value in the trigger stays the label alone. The option grows to fit it.

Also takes the attributes of its element.

### SelectItemIndicator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `keepMounted` | `boolean` |  | Whether to keep the HTML element in the DOM when the item is not selected. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectItemLeading

Also takes the attributes of its element.

### SelectItemText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectPopup

Also takes the attributes of its element.

### SelectPortal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null>` |  | A parent element to render the portal element into. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectScrollDownArrow

| 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 \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectScrollUpArrow

| 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 \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectSeparator

Also takes the attributes of its element.

### SelectTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `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 \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### SelectValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| ((value: any) => React.ReactNode)` |  | Accepts a function that returns a `ReactNode` to format the selected value. Treat the value as read-only: in `multiple` mode it may be a shared frozen array when nothing is selected. |
| `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 \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

## Changes

- 0.12.0 (Breaking Changes): `ComboboxSelect` always takes typing on a phone, as on a desktop: tapping the field focuses it and typing filters; `create` and remote search work in the field. The phone-only pick-only mode and bottom sheet from 0.10.5 are gone, with their props `sheetThreshold`, `sheetTitle` and `messages.search` / `done` / `close`. A pick-only field uses `Select`. The list still picks its side once and doesn't flip while the keyboard opens.
- 0.10.0 (Breaking Changes): Field frames (`Input`, `Textarea`, `InputGroup`, `Select`, `Combobox`, `ComboboxSelect`, `Composer`, option `Card`, `SearchTrigger`) are drawn at 1px in `line-field` instead of 1.5px, on the phone too.
- 0.9.4 (Fixed): A `SelectItem` with a `SelectItemDescription` is named by its `SelectItemText` alone and described by the description, so screen readers no longer read the two run together as the option's name. Items without a description are unchanged.
- 0.9.0 (Fixed): In a `SelectItem` with a `SelectItemLeading`, the `SelectItemDescription` starts under the label instead of under the icon.
- 0.8.3 (Added): `SelectItemDescription`: an optional second line under an option's label, for what the value means. The trigger still shows only the label.
- 0.8.3 (Fixed): A `SelectItem` grows with its content and keeps 6px above and below its text. A one-line item stays 36px.
- 0.5.37 (Fixed): Brutal `Combobox` keeps its shadow when open, as `Select` does: the control lifts 1px with `shadow-raft-md` instead of dropping the shadow. In Brutal, `SelectContent` and `ComboboxContent` now default `sideOffset` to 8px (was 4px), so the open trigger's shadow stays clear of the popup instead of running into it. Elegant keeps 4px; an explicit `sideOffset` still wins.