选择器

一个常见的表单组件，用于在下拉菜单中选择预定义的值。

安装


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

基本用法

import {
  Select,
  SelectContent,
  SelectItemContent,
  SelectTriggerGroup,
} from "@/components/ui/select";

<Select>
  <SelectTriggerGroup placeholder="请选择一个水果" />
  <SelectContent>
    <SelectItemContent value="apple">苹果</SelectItemContent>
    <SelectItemContent value="banana">香蕉</SelectItemContent>
  </SelectContent>
</Select>

组件结构

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

功能特性

自定义样式

对齐方式

支持滚动

多选

为 <Select> 根组件添加 multiple 属性以启用多选功能。

分组

使用 SelectGroup 和 SelectGroupLabel 将选项组织成不同的区域。

提示

此组件使用了 animate-popup 工具类，以确保与其他浮层组件的动画一致性。你可以在 CSS 文件中自定义过渡效果、缓动函数和持续时间。详见动画指南。

状态

禁用状态

错误状态

实用示例

自定义渲染

你可以在使用 items 属性保障无障碍的同时，自定义渲染的内容。

受控模式

通过编程方式控制选择器的值。

追踪状态

你可以追踪选择器的状态，并利用它来显示额外信息。

API 参考

基础组件

Base Select API 参考

复合组件

SelectTriggerGroup

一个高阶的触发按钮组件，它将 Trigger、Value 和 Icon 组合成一个带样式的单一元素。它会自动处理尺寸、图标和占位符文本。

属性	类型	默认值	描述
`size`	`"default" \| "sm"`	`"default"`	控制触发按钮的高度和内边距。
`placeholder`	`string`	`-`	未选择任何值时显示的文本。
`indicatorIcon`	`React.ReactNode`	`<ChevronDownIcon />`	指示器图标。如果不提供，则默认使用向下箭头。
`indicatorPlacement`	`"start" \| "end"`	`"end"`	将指示器图标定位在触发按钮的起始或末尾。
`children`	`ReactNode`	`-`	已选值的显示内容（通常由根组件自动传递）。
`className`	`string`	`-`	额外的 CSS 类名。
`...props`	`BaseSelect.Trigger`	`-`	将所有其他属性传递给底层的 `BaseSelect.Trigger`。

SelectContent

一个复合组件，包装了 Portal、Positioner、Popup、List 和滚动按钮。

属性	类型	默认值	描述
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	希望在下拉内容相对于触发按钮的哪一侧显示。
`align`	`"start" \| "center" \| "end"`	`"start"`	希望下拉内容相对于触发按钮的对齐方式。
`sideOffset`	`number`	`4`	距离触发按钮的像素值。
`alignOffset`	`number`	`0`	从 `align` 指定边缘的像素偏移量。
`alignItemWithTrigger`	`boolean`	`false`	是否将已选项与触发按钮的文本对齐。
`children`	`ReactNode`	`-`	选项列表（`SelectItem` 或 `SelectItemContent`）。
`className`	`string`	`-`	用于弹窗容器的额外 CSS 类名。
`...props`	`BaseSelect.Popup`	`-`	将所有其他属性传递给底层的 `BaseSelect.Popup`。

SelectItemContent

一个便捷的列表项组件。它将 Item、ItemText 和 ItemIndicator（选中图标）组合成单个组件，并管理选中状态的样式和布局。

属性	类型	默认值	描述
`value`	`string`	必填	选项被选中时要提交的值。
`disabled`	`boolean`	`false`	为 `true` 时，阻止用户与此选项交互。
`indicatorIcon`	`React.ReactNode`	`<CheckIcon />`	选项被选中时显示的自定义图标。
`indicatorPlacement`	`"start" \| "end"`	`"end"`	选择指示器图标的位置。
`children`	`ReactNode`	`-`	选项的文本标签。
`className`	`string`	`-`	额外的 CSS 类名。
`...props`	`BaseSelect.Item`	`-`	将所有其他属性传递给底层的 `BaseSelect.Item`。