Forms
Select
Pick one from a short list. Base UI Select: pass items to the root so the trigger can show the label, and the popup opens over the trigger.
packages/design-system/components/ui/select.tsx
Examples
Anatomy
- 01Trigger, filled pill with a chevron
- 02Value or placeholder
- 03Popup, blurred and dark
- 04Groups, labels and items with a check
Usage
import {
Select, SelectContent, SelectItem, SelectTrigger, SelectValue,
} from "@repo/design-system/components/ui/select";
const timelines = [
{ label: "This month", value: "month" },
{ label: "This quarter", value: "quarter" },
];
<Select items={timelines} value={timeline} onValueChange={setTimeline}>
<SelectTrigger>
<SelectValue placeholder="Deadline in..." />
</SelectTrigger>
<SelectContent>
{timelines.map((option) => (
<SelectItem key={option.value} value={option.value}>{option.label}</SelectItem>
))}
</SelectContent>
</Select>Props
| Prop | Type | Default | Description |
|---|---|---|---|
| items | { label, value }[] | Record<string, ReactNode> | none | On the root. Lets SelectValue show the label for the chosen value before the popup has mounted. |
| value / defaultValue | string | null | none | Controlled or uncontrolled value, on the root. |
| onValueChange | (value, details) => void | none | Called with the new value. |
| SelectTrigger size | "default" | "sm" | "default" | 36 or 32px tall. |
| side | "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end" | none | Which side of the trigger the popup opens on. |
| align | "start" | "center" | "end" | "center" | How the popup lines up with the trigger along that side. |
| sideOffset | number | 4 | The gap between trigger and popup, in pixels. |
| alignItemWithTrigger | boolean | true | On SelectContent. Opens with the chosen item over the trigger, macOS style. Set false for a dropdown. |
| className | string | none | Merged last with cn(). Use it for layout (width, margin), not to restyle the component. |
Guidance
Do
- Pass items to the root.
- Use it for five to fifteen options.
Don't
- Use it for two or three options. Radios show them all at once.
- Use it when people need to search. That is a combobox.