Select

A select lets the user pick one option (or several) from a list bound to a form field. Use it for a known, finite set of choices; for a searchable list of actions or a command palette, use Command instead.

Preview

Installation

npx shadcn@latest add @cubby-ui/select

Usage

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

<Select>
  <SelectLabel />
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent />
</Select>

Composition

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

SelectContent composes the portal, backdrop, positioner, and popup internally. Pass your options as items on Select and render SelectItem children inside SelectContent.

Examples

Controlled

Use value and onValueChange on Select to drive the selection yourself.

With Groups

Wrap items in SelectGroup with a SelectGroupLabel to organize them.

With Icons

Render an icon alongside the label inside each SelectItem.

Multiple Selection

Set multiple on Select to let the user pick several options.

With Scroll

Long lists scroll inside SelectContent with fading scroll edges.

Align Item with Trigger

Set alignItemWithTrigger on SelectContent to overlay the selected item on the trigger.

Object Values

Use objects as values instead of primitives. The itemToStringValue prop converts objects to strings for form submission.

Elevated Variant

On a Card, Dialog, or popover surface, the opaque default trigger collapses into its parent. Use variant="elevated" on SelectTrigger for a translucent overlay that adapts to the substrate. See the Surfaces docs.

Form Integration

Use Field with SelectLabel for labeling. See the Forms guide for more patterns.

API Reference

The Select component is built on top of Base UI's Select. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Select documentation.

Props

SelectLabel

Accessible label for the select trigger. Wraps Base UI's Select.Label. Renders a <div>: clicking it focuses the trigger without opening the popup.

SelectTrigger

Button that opens the dropdown when clicked. Wraps Base UI's Select.Trigger.

SelectContent

Dropdown container for the option list with positioning. Composes Base UI's Select.Positioner and Select.Popup. Props are forwarded to Select.Popup.