# Select

A listbox for picking a single value from a group of options.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="select" />

<ComponentPreview name="select" title="select.tsx">
<SelectDemo />
</ComponentPreview>

A select lets the user pick one option from a list. The listbox anchors to the trigger and aligns the selected item with the trigger label, matching native select behavior.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add select
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install @floating-ui/react-dom lucide-react
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="select" title="components/ui/select.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="select.tsx"
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";
```

```tsx title="select.tsx"
<Select>
  <SelectTrigger>
    <SelectValue placeholder="Pick a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="banana">Banana</SelectItem>
  </SelectContent>
</Select>
```

## Groups [#groups]

<ComponentPreview name="select-groups" title="select-groups.tsx" src="examples/select-groups.tsx">
<SelectGroups />
</ComponentPreview>

Wrap items in `SelectGroup` and render a heading with `SelectLabel`. Screen readers announce each group as a labeled list.
## Disabled [#disabled]

<ComponentPreview name="select-disabled" title="select-disabled.tsx" src="examples/select-disabled.tsx">
<SelectDisabled />
</ComponentPreview>

`disabled` on `Select` locks the trigger and prevents opening. Disabled items stay visible in the list for context but cannot be selected.

## Invalid [#invalid]

<ComponentPreview name="select-invalid" title="select-invalid.tsx" src="examples/select-invalid.tsx">
<SelectInvalid />
</ComponentPreview>

Set `aria-invalid` on `SelectTrigger` to apply the destructive border and focus ring.

## Position [#position]

By default the listbox uses `item-aligned` placement. The selected item overlaps the trigger so the list reads like a native select. Pass `position="popper"` to anchor the listbox under the trigger instead.

```tsx
<SelectContent position="popper" align="start" sideOffset={4}>
  <SelectItem value="apple">Apple</SelectItem>
</SelectContent>
```

`side`, `align`, `sideOffset`, and `alignOffset` only apply when `position="popper"`.

## Align item [#align-item]

<ComponentPreview name="select-align-item" title="select-align-item.tsx" src="examples/select-align-item.tsx">
<SelectAlignItem />
</ComponentPreview>

Toggle between `item-aligned` (default) and `popper` placement at runtime. Item-aligned overlaps the selected item with the trigger so the list reads like a native select. Popper anchors the list below the trigger.

## Scrollable [#scrollable]

<ComponentPreview name="select-scrollable" title="select-scrollable.tsx" src="examples/select-scrollable.tsx">
<SelectScrollable />
</ComponentPreview>

Long lists scroll inside the listbox. The viewport caps its height and keeps the selected item visible while scrolling.

## Keyboard [#keyboard]

| Key | Action |
| :-- | :-- |
| `Space` / `Enter` | Open the listbox when the trigger is focused. Select the focused item when the listbox is open. |
| `ArrowUp` / `ArrowDown` | Move focus to the previous / next item. |
| `Home` / `End` | Move focus to the first / last item. |
| `a`–`z` | Type-ahead. Jumps to the next item whose label starts with the typed prefix. |
| `Esc` | Close the listbox and return focus to the trigger. |

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `select-trigger`, `select-value`, `select-content`, `select-viewport`, `select-group`, `select-label`, `select-item`, `select-item-text`, `select-separator` |
| `data-state` | `open` \| `closed` on the trigger and content. `checked` \| `unchecked` on items. |
| `data-highlighted` | Present on the focused item. |
| `data-disabled` | Present on disabled trigger and items. |
| `data-placeholder` | Present on the trigger when no value is selected. |
| `data-side` / `data-align` | Placement used by popper and item-aligned modes. |

## API Reference [#api-reference]

### Select [#select]

<PropsTable />

### SelectTrigger [#selecttrigger]

<PropsTable rows={[{"name":"as","type":"React.ElementType","description":"Renders a different root element or component. Defaults to button."},{"name":"size","type":"sm | default","default":"default","description":"Trigger height."},{"name":"disabled","type":"boolean","default":"false","description":"Disables the trigger in addition to the root disabled prop."}]} />

### SelectValue [#selectvalue]

<PropsTable rows={[{"name":"placeholder","type":"React.ReactNode","description":"Rendered when no value is selected."}]} />

### SelectContent [#selectcontent]

<PropsTable />

### SelectItem [#selectitem]

<PropsTable rows={[{"name":"value","type":"string","description":"Value submitted when this item is selected. Required."},{"name":"disabled","type":"boolean","default":"false","description":"Keeps the item visible but unselectable."},{"name":"textValue","type":"string","description":"Plain text used for type-ahead matching. Use when children are not plain text."}]} />

### SelectGroup and SelectLabel [#selectgroup-and-selectlabel]

`SelectGroup` clusters items under a heading rendered by `SelectLabel`.

### SelectSeparator [#selectseparator]

Renders a horizontal rule between groups or items.

### SelectScrollUpButton and SelectScrollDownButton [#selectscrollupbutton-and-selectscrolldownbutton]

Render inside `SelectContent` to auto-scroll when the pointer reaches the edge of a long list.

## Motion [#motion]

The listbox fades and scales in through Frakment's motion engine. Pass `motion` on `SelectContent`:

```tsx
<SelectContent motion="200 ease-out">Content</SelectContent>
```

`motion` accepts `"off"`, `"150"`, `"150 ease-out"`, or `"150 cubic-bezier(0.4, 0, 0.2, 1)"`. The default is a 150ms smooth-out curve. `prefers-reduced-motion` wins and the listbox appears instantly.

## Accessibility [#accessibility]

- `SelectTrigger` exposes `role="combobox"`, `aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls`. Do not set them manually.
- Pair the trigger with a `Label` or `FieldLabel` using `htmlFor` so screen readers announce the field name.
- Disabled items stay visible but are skipped by keyboard navigation and type-ahead.
- `Escape` closes the listbox. Outside pointer down also closes it.
- Focus moves to the selected item on open and returns to the trigger on close.

## Best Practices [#best-practices]

- Use select for five or more options. Fewer options belong in a radio group.
- Always provide a placeholder. `SelectValue placeholder` keeps the empty state legible.
- Group long lists. `SelectGroup` and `SelectLabel` help users scan by category.
- Prefer `popper` for toolbars. The anchored list feels native inside forms; popper reads better alongside inline controls.

## Related Components [#related-components]

- [Dropdown Menu](/docs/components/web/dropdown-menu): action menu with arbitrary content
- [Radio Group](/docs/components/radio-group): visible options
- [Field](/docs/components/field): form field wrapper with label and description