Select

A common form component for choosing a predefined value in a dropdown menu.

Installation


pnpm dlx shadcn@latest add @lumi-ui/select

Basic 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>

Recipes

Scrollable

When the content exceeds the viewport height, scroll buttons automatically appear.

With Groups

Use SelectGroup and SelectLabel to organize items into sections.

Multiple selection

Add the multiple prop to the <Select> component to allow multiple selections.

Item Aligned

Use position="item-aligned" for classic OS-style positioning where the selected item aligns with the trigger.

Disabled

Disable the entire select or individual items.

Data-Driven Items

Pass an array of objects to the items prop to automatically handle value-label lookups and rendering.

Custom Render

You can customize the rendered content while still using the items prop for accessibility.

Controlled

Control the value state programmatically.

Track State

You can track the state of the select and use it to display additional information.

Anatomy

<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel />
      <SelectItem />
    </SelectGroup>
    <SelectSeparator />
  </SelectContent>
</Select>

Component	Role
`Select`	Root component that manages state and value.
`SelectTrigger`	Button that toggles the dropdown.
`SelectValue`	Displays the selected value or placeholder.
`SelectContent`	Popover container with positioning and scroll handling.
`SelectGroup`	Groups related items together.
`SelectLabel`	Label for a group of items.
`SelectItem`	Individual selectable option.
`SelectSeparator`	Visual divider between items or groups.
`SelectScrollUpButton`	Scroll control at the top of the list.
`SelectScrollDownButton`	Scroll control at the bottom of the list.

Migration from shadcn/ui

Component Naming & Structure

Our component wraps Base UI's Select primitive but maintains shadcn/ui's naming convention for easy migration.

shadcn/ui	Lumi UI	Notes
`Select`	`Select`	Supports `items` and `multiple` props.
`SelectTrigger`	`SelectTrigger`	Identical usage.
`SelectValue`	`SelectValue`	Identical usage.
`SelectContent`	`SelectContent`	Identical usage.
`SelectItem`	`SelectItem`	Identical usage.
`SelectGroup`	`SelectGroup`	Identical usage.
`SelectLabel`	`SelectLabel`	Identical usage.

Key Differences & New Features

Feature	Lumi UI	shadcn/ui (Radix)
Label Rendering	Automatic via `items` prop	Manual mapping required
Multi-select	Native `multiple` prop	Requires custom implementation
Positioning	`popper` or `item-aligned`	Mostly `popper`
Arrow	Optional (removed by default)	Included by default

Migration Example

The Radix Way

Requires manual mapping for labels if values differ.

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="banana">Banana</SelectItem>
  </SelectContent>
</Select>