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,
  SelectItemContent,
  SelectTriggerGroup,
} from "@/components/ui/select";

<Select>
  <SelectTriggerGroup placeholder="Select a fruit" />
  <SelectContent>
    <SelectItemContent value="Apple">Apple</SelectItemContent>
  </SelectContent>
</Select>

Anatomy

<Select>   
  <SelectTriggerGroup />
  <SelectContent>
    <SelectGroup>
      <SelectGroupLabel />
      <SelectItemContent />
    </SelectGroup>
  </SelectContent> 
</Select>

Features

Item Aligned

Custom Trigger

Scrollable

Multiple selection

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

With Groups

Use SelectGroup and SelectGroupLabel to organize items into sections.

Note

This component uses the animate-popup utility class to ensure consistency with other overlays. You can customize transitions, easing, and duration in css file. See details in Animation Guide.

States

Disabled

Invalid

Cookbook

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.

Form Integration

API Reference

Primitives

Base Select API Reference

Composite Components

SelectTriggerGroup

A high-level trigger component that combines the Trigger, Value, and Icon into a single styled element. It handles sizing, icons, and placeholder text automatically.

Prop	Type	Default	Description
`size`	`"default" \| "sm" \| "lg"`	`"default"`	Controls the height and padding of the trigger.
`placeholder`	`string`	`-`	Text to display when no value is selected.
`indicatorIcon`	`React.ReactNode`	`<ChevronDownIcon />`	The indicator icon. If not provided, defaults to a chevron.
`indicatorPlacement`	`"start" \| "end"`	`"end"`	Positions the indicator icon either at the start or end of the trigger.
`children`	`ReactNode`	`-`	The selected value content (usually passed automatically by the Root).
`className`	`string`	`-`	Additional CSS classes.
`...props`	`BaseSelect.Trigger`	`-`	Passes all other props to the underlying `BaseSelect.Trigger`.

SelectContent

A composite component that wraps the Portal , Positioner, Popup, List, and scroll buttons.

Prop	Type	Default	Description
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	The preferred side of the trigger to render the content.
`align`	`"start" \| "center" \| "end"`	`"start"`	The preferred alignment against the trigger.
`sideOffset`	`number`	`4`	The distance in pixels from the trigger.
`alignOffset`	`number`	`0`	An offset in pixels from the `align` edge.
`alignItemWithTrigger`	`boolean`	`false`	Whether the selected item should be aligned with the trigger.
`children`	`ReactNode`	`-`	The list of items (`SelectItem` or `SelectItemContent`).
`className`	`string`	`-`	Additional CSS classes for the popup container.
`...props`	`BaseSelect.Popup`	`-`	Passes all other props to the underlying `BaseSelect.Popup`.

SelectItemContent

A convenience component for list items. It combines the Item, ItemText, and ItemIndicator (check icon) into a single component, managing styles and layouts for selected states.

Prop	Type	Default	Description
`value`	`string`	Required	The value of the item to be submitted when selected.
`disabled`	`boolean`	`false`	When `true`, prevents the user from interacting with the item.
`indicatorIcon`	`React.ReactNode`	`<CheckIcon />`	Custom icon to show when the item is selected.
`indicatorPlacement`	`"start" \| "end"`	`"end"`	Positions the selection indicator icon.
`children`	`ReactNode`	`-`	The text label of the item.
`className`	`string`	`-`	Additional CSS classes.
`...props`	`BaseSelect.Item`	`-`	Passes all other props to the underlying `BaseSelect.Item`.