Select

A dropdown selection component with support for grouped items, separators, and multiple sizes. Built on top of Base UI's Select primitive.

$npx shadcn add @patchui/select

Basic

Grouped

Sizes

Disabled Item

Usage

import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectPopup,
  SelectItem,
  SelectGroup,
  SelectGroupLabel,
  SelectSeparator,
} from "@patchui/react";
 
// Basic select
<Select defaultValue="apple">
  <SelectTrigger>
    <SelectValue placeholder="Choose a fruit…" />
  </SelectTrigger>
  <SelectPopup>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="banana">Banana</SelectItem>
    <SelectItem value="cherry">Cherry</SelectItem>
  </SelectPopup>
</Select>
 
// Grouped items
<Select defaultValue="react">
  <SelectTrigger className="w-56">
    <SelectValue placeholder="Choose a framework…" />
  </SelectTrigger>
  <SelectPopup>
    <SelectGroup>
      <SelectGroupLabel>Frontend</SelectGroupLabel>
      <SelectItem value="react">React</SelectItem>
      <SelectItem value="vue">Vue</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
      <SelectGroupLabel>Backend</SelectGroupLabel>
      <SelectItem value="node">Node.js</SelectItem>
    </SelectGroup>
  </SelectPopup>
</Select>

Props

SelectTrigger

Prop	Type	Default	Description
size	"sm" \| "md" \| "lg"	"md"	The size of the trigger button.
className	string	-	Additional CSS classes.

SelectValue

Prop	Type	Default	Description
placeholder	string	-	Text shown when no value is selected.
className	string	-	Additional CSS classes.

SelectPopup

Prop	Type	Default	Description
side	"top" \| "bottom" \| "left" \| "right"	"bottom"	Which side of the trigger the popup appears on.
sideOffset	number	4	Distance in pixels between the popup and trigger.
align	"start" \| "center" \| "end"	"start"	Alignment of the popup relative to the trigger.
alignOffset	number	0	Offset for alignment in pixels.
alignItemWithTrigger	boolean	true	Whether to align the selected item with the trigger.

SelectItem

Prop	Type	Default	Description
value	string	-	The value of this option, used for form submission and selection state.
disabled	boolean	false	Whether this item is disabled.
className	string	-	Additional CSS classes.

Compound Components

Component	Description
Select	Root component that manages open/close state and value.
SelectTrigger	Styled trigger button with size variants and chevron icon.
SelectValue	Displays the selected value text inside the trigger.
SelectPopup	Portal-rendered popup with positioner. Also exported as SelectContent.
SelectItem	An individual option with check indicator.
SelectGroup	Groups related items together.
SelectGroupLabel	Label for a group of items.
SelectSeparator	A visual separator between items or groups.

Notes

Portal rendering: The popup renders via a portal, so it appears above all other content regardless of overflow or stacking context.
Composition: Use SelectTrigger + SelectValue for the trigger. SelectTrigger renders the styled button with a chevron icon, and SelectValue displays the currently selected item text.
Keyboard navigation: Supports arrow keys, type-ahead search, Home/End, and Enter/Space for selection.