Select

Powered by

Base UIShadcn UILucide

Installation

When to use

Select components provide single-option selection from a list of options. Use this decision tree:

Usage

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

<Select>
  <SelectTrigger className="w-[180px]">
    <SelectValue placeholder="Theme" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="light">Light</SelectItem>
    <SelectItem value="dark">Dark</SelectItem>
    <SelectItem value="system">System</SelectItem>
  </SelectContent>
</Select>

Anatomy

The Select component is built with Base UI primitives:

<Select> (Root Container)
├── <SelectTrigger> (Button)
│   ├── <SelectValue> (Placeholder/Selected)
│   └── <ChevronDown> Icon
├── <SelectContent> (Dropdown)
│   ├── Portal rendering
│   ├── Positioning system
│   └── <SelectItem> (Options)
│       ├── Checkmark indicator
│       └── Item text
└── Keyboard/Mouse handling

Props

Resolving labels in the trigger

<SelectValue> accepts three forms for the trigger label, in order of preference:

1. No children — the registry wrapper defers to Base UI's native resolution. Pass an items map on <Select> to look up the label, otherwise the raw value is stringified.
2. Static children — render the same node regardless of value (rarely useful for selects).
3. Render-prop children — (value) => ReactNode. Returning null/undefined falls back to placeholder. Use this for rich trigger content (icon + label, avatar + name, status dot + label) that mirrors the selected item.

<Select items={{ '1': 'Any', '2': 'Read', '3': 'Write' }} value="1">
  <SelectTrigger>
    <SelectValue placeholder="Select operation" />
  </SelectTrigger>
  …
</Select>

// or, for rich content:
<SelectValue placeholder="Assign to teammate">
  {(value) => {
    const user = users.find((u) => u.value === value);
    return user ? <UserContent user={user} /> : null; // null → placeholder
  }}
</SelectValue>

Examples

Scrollable

Groups

Disabled options

With description

With icon

Status indicator

Avatars

Custom rendering

Object values

Placeholder and clearable

Error state

Loading state

Enum-backed value (label ≠ String(value))

Form

Keyboard interactions

Accessibility

• SelectTrigger is a real button with aria-haspopup="listbox" and aria-expanded; the listbox carries role="listbox" and each item role="option" with aria-selected.
• Provide a visible label via <Label htmlFor> or wrap the select in a <Field> so the selected value has a programmatic name.
• onValueChange is the Radix-style single-argument (value: string) => void; the compat layer narrows Base UI's (value, details) signature.
• For large option lists (>20), prefer Combobox so users can type-ahead-filter. Select's typeahead only jumps to matching first letters.

Credits

• We use Base UI for the select component.
• We take our inspiration from Shadcn UI for the select style.