Select

Model

Installation

pnpm dlx shadcn@latest add @paneui/select

Usage

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

<Select items={fruits} defaultValue="apple">
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="pear">Pear</SelectItem>
  </SelectContent>
</Select>

Composition

Select
├── SelectTrigger
│   └── SelectValue
└── SelectContent
    ├── SelectGroup
    │   ├── SelectLabel
    │   └── SelectItem
    ├── SelectSeparator
    └── SelectItem

Examples

Placeholder

Sizes

With Icons

Use when icons help tell the options apart.

Disabled

Controlled

Use when other UI reacts to the choice.

RTL

Positioning

By default the popup opens over the trigger with the selected item aligned to it (alignItemWithTrigger), like a native select. Set it to false to drop the list below instead.

Keyboard

Space, Enter or the arrow keys open the list. Arrow keys move, typing jumps to a matching item, Enter selects and Esc closes.

API Reference

Built on the Select primitive. Only the props this library adds or changes are listed; everything else passes through.

Re-export of the primitive root. Also accepts every prop of Select.Root.

items: { value: any; label: ReactNode }[] | Record<string, ReactNode>; Lets SelectValue show the label for the current value.
value: any; Controlled value.
defaultValue: any; Initial value when uncontrolled.
onValueChange: (value: any, eventDetails) => void; Called when an item is chosen.
multiple= false: boolean; Allow several values.
disabled= false: boolean; Disable the whole control.

Prop	Type	Default	Description
items	{ value: any; label: ReactNode }[] \| Record<string, ReactNode>	—	Lets `SelectValue` show the label for the current value.
value	any	—	Controlled value.
defaultValue	any	—	Initial value when uncontrolled.
onValueChange	(value: any, eventDetails) => void	—	Called when an item is chosen.
multiple	boolean	false	Allow several values.
disabled	boolean	false	Disable the whole control.

SelectTrigger

Raised button with a trailing up/down chevron. Full width with a 10rem minimum. Also accepts every prop of Select.Trigger.

size= "default": "xs" | "sm" | "default" | "lg"; Height 24 / 28 / 32 / 36px. Defaults to the Select size, then a sized Field.

Prop	Type	Default	Description
size	"xs" \| "sm" \| "default" \| "lg"	"default"	Height 24 / 28 / 32 / 36px. Defaults to the `Select` size, then a sized `Field`.

data-popup-open: Present while the list is open.
data-size: The resolved size.

Data attribute	Description
data-popup-open	Present while the list is open.
data-size	The resolved size.

SelectValue

Shows the selected label, truncated. Also accepts every prop of Select.Value.

children: ReactNode | (value: any) => ReactNode; Custom rendering of the selected value.

Prop	Type	Default	Description
children	ReactNode \| (value: any) => ReactNode	—	Custom rendering of the selected value.

data-placeholder: Present when nothing is selected (muted text).

Data attribute	Description
data-placeholder	Present when nothing is selected (muted text).

SelectContent

Portal, positioner, popup and scrollable list with scroll arrows. Also accepts every prop of Select.Popup.

side= "bottom": "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"; Side to open on when not aligned with the trigger.
sideOffset= 6: number; Gap from the trigger in px.
align= "center": "start" | "center" | "end"; Alignment against the trigger.
alignItemWithTrigger= true: boolean; Overlay the trigger so the selected item sits on top of it.

Prop	Type	Default	Description
side	"top" \| "right" \| "bottom" \| "left" \| "inline-start" \| "inline-end"	"bottom"	Side to open on when not aligned with the trigger.
sideOffset	number	6	Gap from the trigger in px.
align	"start" \| "center" \| "end"	"center"	Alignment against the trigger.
alignItemWithTrigger	boolean	true	Overlay the trigger so the selected item sits on top of it.

SelectItem

Option row with a check on the right when selected. Also accepts every prop of Select.Item.

value: any; Value chosen by this item.
disabled= false: boolean; Dim the item and skip it.

Prop	Type	Default	Description
value	any	—	Value chosen by this item.
disabled	boolean	false	Dim the item and skip it.

data-highlighted: Present on the item under the pointer or keyboard focus.
data-selected: Present on the selected item.

Data attribute	Description
data-highlighted	Present on the item under the pointer or keyboard focus.
data-selected	Present on the selected item.

SelectGroup

Re-export. Groups items under a SelectLabel. Also accepts every prop of Select.Group.

SelectLabel

Small muted heading for a group. Also accepts every prop of Select.GroupLabel.

SelectSeparator

Also accepts every prop of Select.Separator.