Select

select

下拉选择 · Base UI overlay 单选 + items 自动 label

用法

基础用法

items 提供选项数据，placeholder 作占位。

tsx

<Select items={fonts} placeholder="请选择字体">
  <SelectTrigger />
  <SelectContent>
    {fonts.map((f) => (
      <SelectItem key={f.value} value={f.value}>
        {f.label}
      </SelectItem>
    ))}
  </SelectContent>
</Select>

默认已选值

非受控写法用 defaultValue 预设选中项。

tsx

<Select items={fonts} defaultValue="serif">
  <SelectTrigger />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

尺寸

SelectTrigger 的 size 提供 sm / md / lg。

tsx

<Select items={fonts} defaultValue="mono">
  <SelectTrigger size="sm" />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

无效态

SelectTrigger 传 invalid 标红（独立使用时）。

tsx

<Select items={fonts} placeholder="请选择字体">
  <SelectTrigger invalid />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

禁用态

Select 传 disabled 屏蔽整个下拉。

tsx

<Select items={fonts} defaultValue="sans" disabled>
  <SelectTrigger />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

何时用

从一组固定选项里单选一项（选项较多、需要收纳成下拉）。选项少且需全部可见用 Radio；多选用 CheckboxGroup；自由文本用 Input。给 items（{value,label} 数组）让 Trigger 显示选中项 label 而非 raw value。

导入

import { Select, SelectTrigger, SelectContent, SelectItem } from "@hulianui/ui"

Props

Select 继承 Base UI Select.Root 属性（除 items 被下方覆盖外，如 value/defaultValue/onValueChange/disabled…）。

Select

名称	类型	默认	说明
items	`ReadonlyArray<{ value: string ｜ null; label: ReactNode }>`	—	选项数据；Base UI 据此让 Trigger 显示选中项 label
placeholder	`ReactNode`	—	无选中值时的占位文本（瑚琏注入 value:null 项实现，rc.0 无 Value.placeholder prop）

SelectTrigger

名称	类型	默认	说明
size	`"sm" ｜ "md" ｜ "lg"`	`"md"`	尺寸
invalid	`boolean`	`false`	独立使用（非 Field 内）时手动置无效态皮肤
className	`string`	—	透传类名

SelectContent

名称	类型	默认	说明
side	`"top" ｜ "bottom"`	`"bottom"`	弹出方向
align	`"start" ｜ "center" ｜ "end"`	—	对齐
sideOffset	`number`	—	偏移量

SelectItem

名称	类型	默认	说明
value*	`string`	—	选项值（本批仅 string 值）
disabled	`boolean`	`false`	禁用此项

Events

Select 透传 Base UI Select.Root 的常用事件。

事件	类型	说明
onValueChange	`(value: string ｜ null, eventDetails) => void`	选中值变化回调（透传 Base UI `Select.Root`）
onOpenChange	`(open: boolean, eventDetails) => void`	下拉开合变化回调（透传 Base UI `Select.Root`）

Slots

插槽	类型	说明
SelectContent.children*	`ReactNode`	一组 `SelectItem`
SelectItem.children*	`ReactNode`	选项展示内容

禁忌 / 坑

占位文本通过 Select 的 placeholder prop 传，不要给 Select.Value 传 placeholder——见 [[base-ui-select-rc0-no-value-placeholder-prop-inject-null-item]]：本项目锁 Base UI rc.0，其 Select.Value 没有 placeholder prop（那是 v1.2+），瑚琏靠注入一个 value:null 的 items 项实现占位 label。items 与 SelectItem 的 value 要对应，否则 Trigger 显示 raw value 而非 label。

Playground

占位文案sizeside禁用无效态

<Select items={items} placeholder="请选择字体" defaultValue="…">
  <SelectTrigger size="md" />
  <SelectContent side="bottom">
    {items.map((it) => <SelectItem key={it.value} value={it.value}>{it.label}</SelectItem>)}
  </SelectContent>
</Select>

Select

select

下拉选择 · Base UI overlay 单选 + items 自动 label

用法

基础用法

items 提供选项数据，placeholder 作占位。

tsx

<Select items={fonts} placeholder="请选择字体">
  <SelectTrigger />
  <SelectContent>
    {fonts.map((f) => (
      <SelectItem key={f.value} value={f.value}>
        {f.label}
      </SelectItem>
    ))}
  </SelectContent>
</Select>

默认已选值

非受控写法用 defaultValue 预设选中项。

tsx

<Select items={fonts} defaultValue="serif">
  <SelectTrigger />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

尺寸

SelectTrigger 的 size 提供 sm / md / lg。

tsx

<Select items={fonts} defaultValue="mono">
  <SelectTrigger size="sm" />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

无效态

SelectTrigger 传 invalid 标红（独立使用时）。

tsx

<Select items={fonts} placeholder="请选择字体">
  <SelectTrigger invalid />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

禁用态

Select 传 disabled 屏蔽整个下拉。

tsx

<Select items={fonts} defaultValue="sans" disabled>
  <SelectTrigger />
  <SelectContent>{/* SelectItem… */}</SelectContent>
</Select>

何时用

导入

import { Select, SelectTrigger, SelectContent, SelectItem } from "@hulianui/ui"

Props

Select 继承 Base UI Select.Root 属性（除 items 被下方覆盖外，如 value/defaultValue/onValueChange/disabled…）。

Select

名称	类型	默认	说明
items	`ReadonlyArray<{ value: string ｜ null; label: ReactNode }>`	—	选项数据；Base UI 据此让 Trigger 显示选中项 label
placeholder	`ReactNode`	—	无选中值时的占位文本（瑚琏注入 value:null 项实现，rc.0 无 Value.placeholder prop）

SelectTrigger

名称	类型	默认	说明
size	`"sm" ｜ "md" ｜ "lg"`	`"md"`	尺寸
invalid	`boolean`	`false`	独立使用（非 Field 内）时手动置无效态皮肤
className	`string`	—	透传类名

SelectContent

名称	类型	默认	说明
side	`"top" ｜ "bottom"`	`"bottom"`	弹出方向
align	`"start" ｜ "center" ｜ "end"`	—	对齐
sideOffset	`number`	—	偏移量

SelectItem

名称	类型	默认	说明
value*	`string`	—	选项值（本批仅 string 值）
disabled	`boolean`	`false`	禁用此项

Events

Select 透传 Base UI Select.Root 的常用事件。

事件	类型	说明
onValueChange	`(value: string ｜ null, eventDetails) => void`	选中值变化回调（透传 Base UI `Select.Root`）
onOpenChange	`(open: boolean, eventDetails) => void`	下拉开合变化回调（透传 Base UI `Select.Root`）

Slots

插槽	类型	说明
SelectContent.children*	`ReactNode`	一组 `SelectItem`
SelectItem.children*	`ReactNode`	选项展示内容

禁忌 / 坑

占位文本通过 Select 的 placeholder prop 传，不要给 Select.Value 传 placeholder——见 [[base-ui-select-rc0-no-value-placeholder-prop-inject-null-item]]：本项目锁 Base UI rc.0，其 Select.Value 没有 placeholder prop（那是 v1.2+），瑚琏靠注入一个 value:null 的 items 项实现占位 label。items 与 SelectItem 的 value 要对应，否则 Trigger 显示 raw value 而非 label。

Playground

占位文案sizeside禁用无效态

<Select items={items} placeholder="请选择字体" defaultValue="…">
  <SelectTrigger size="md" />
  <SelectContent side="bottom">
    {items.map((it) => <SelectItem key={it.value} value={it.value}>{it.label}</SelectItem>)}
  </SelectContent>
</Select>

Select

用法

基础用法

默认已选值

尺寸

无效态

禁用态

何时用

导入

Props

Select

SelectTrigger

SelectContent

SelectItem

Events

Slots

禁忌 / 坑

相关

Playground

Select

用法

基础用法

默认已选值

尺寸

无效态

禁用态

何时用

导入

Props

Select

SelectTrigger

SelectContent

SelectItem

Events

Slots

禁忌 / 坑

相关

Playground