Select 选择器

基于 reka-ui 的 Select 原语构建的新粗野主义风格下拉选择框，完整支持子组件。

预览

Preview

安装

pnpm dlx brutx-vue@latest add select

用法

<script setup>
import { Select, SelectTrigger, SelectContent, SelectItem, SelectLabel } from 'brutx-ui-vue'
import { SelectGroup, SelectValue } from 'reka-ui'
</script>

<template>
    <Select>
        <SelectTrigger class="w-[280px]">
            <SelectValue placeholder="Select a fruit" />
        </SelectTrigger>
        <SelectContent>
            <SelectGroup>
                <SelectLabel>Fruits</SelectLabel>
                <SelectItem value="apple">Apple</SelectItem>
                <SelectItem value="banana">Banana</SelectItem>
                <SelectItem value="orange">Orange</SelectItem>
                <SelectItem value="grape">Grape</SelectItem>
            </SelectGroup>
        </SelectContent>
    </Select>
</template>

自定义插槽与属性透传

默认插槽用于完全自定义选择器内容，不提供作用域参数。组合原子组件时，Select 接收表单 name、required 和 disabled；触发器的 id 及禁用状态应在插槽内容中直接绑定。

<script setup>
import { ref } from 'vue'
import { Select, SelectTrigger, SelectContent, SelectItem } from 'brutx-ui-vue'
import { SelectValue } from 'reka-ui'
const isDisabled = ref(false)
</script>

<template>
    <Select name="fruit" required :disabled="isDisabled">
        <SelectTrigger id="fruit-select" :disabled="isDisabled" class="w-[280px]">
            <SelectValue placeholder="Select a fruit" />
        </SelectTrigger>
        <SelectContent>
            <SelectItem value="apple">Apple</SelectItem>
            <SelectItem value="banana">Banana</SelectItem>
        </SelectContent>
    </Select>
</template>

自定义触发器（trigger 插槽）

如果你只想替换触发器的样式，同时保留一体化的 options 数据驱动渲染，可以使用具名插槽 trigger。内容下拉区域（<SelectContent>）仍由 options prop 驱动，无需重新实现：

<template>
    <Select
        v-model="selectedValue"
        :options="foodOptions"
    >
        <template #trigger>
            <SelectTrigger class="w-[280px] border-dashed">
                <SelectValue placeholder="请选择食物" />
            </SelectTrigger>
        </template>
    </Select>
</template>

注意：trigger 插槽与 default 插槽互斥。使用 default 插槽时，全部内容由用户接管（需自行提供 <SelectContent>）；使用 trigger 插槽时，只替换触发器，<SelectContent> 仍由组件自动渲染。

一体化用法

除了使用原子组件拼装，还可以使用封装好的一体化 Select 组件，支持传入 options 数组并支持自动分组。

<script setup>
import { ref } from 'vue'
import { Select } from 'brutx-ui-vue'

const selectedValue = ref('')

const foodOptions = [
    { label: '苹果', value: 'apple', category: 'fruits', categoryName: '水果' },
    { label: '香蕉', value: 'banana', category: 'fruits', categoryName: '水果' },
    { label: '胡萝卜', value: 'carrot', category: 'vegetables', categoryName: '蔬菜' },
    { label: '土豆', value: 'potato', category: 'vegetables', categoryName: '蔬菜' },
    { label: '牛奶', value: 'milk' } // 未分组
]
</script>

<template>
    <!-- 基本用法 -->
    <Select
        v-model="selectedValue"
        :options="foodOptions"
        placeholder="选择你喜欢的食物"
        class="w-[280px]"
    />

    <!-- 自动分组用法 -->
    <Select
        v-model="selectedValue"
        :options="foodOptions"
        group-field="category"
        group-label="categoryName"
        placeholder="选择食物（分组）"
        class="w-[280px]"
    />
</template>

使用 v-model

<script setup>
import { ref } from 'vue'
import {
    Select,
    SelectTrigger,
    SelectContent,
    SelectItem,
} from 'brutx-ui-vue'
import { SelectValue } from 'reka-ui'

const selectedFruit = ref('')
</script>

<template>
    <Select v-model="selectedFruit">
        <SelectTrigger class="w-[280px]">
            <SelectValue placeholder="Select a fruit" />
        </SelectTrigger>
        <SelectContent>
            <SelectItem value="apple">Apple</SelectItem>
            <SelectItem value="banana">Banana</SelectItem>
            <SelectItem value="orange">Orange</SelectItem>
        </SelectContent>
    </Select>
</template>

子组件

组件	说明
Select	支持 options 数据源和插槽组合的一体化选择器，内部使用 Reka UI 原语
SelectRoot	Reka UI 根原语，为原子组合提供选择器上下文（从 reka-ui 导入）
SelectValue	Reka UI 原语，显示当前值或占位文本（从 reka-ui 导入）
SelectGroup	Reka UI 原语，将选项组合为一个分组（从 reka-ui 导入）
SelectTrigger	打开下拉菜单的按钮
SelectContent	下拉内容面板
SelectItem	可选项
SelectLabel	分组标签
SelectSeparator	视觉分隔线
SelectScrollUpButton	向上滚动指示器
SelectScrollDownButton	向下滚动指示器

API 参考

Select

Select — 属性

名称	类型	默认值	说明
options	SelectOption[] | undefined	[]	一体化选择器的选项列表；每项提供 label 和非空 value，可选 disabled，并可带用于分组的自定义字段。
详情 声明类型 SelectOption[] | undefined 关联类型 SelectOption 类型定义 — SelectOption export interface SelectOption { label: string value: string disabled?: boolean [key: string]: unknown } 默认值详情 声明 [] 来源: packages/ui/src/components/select/Select.vue 解析值 [] 来源 types.ts:9 packages/ui/src/components/select/types.ts
groupField	string | undefined	undefined	选项对象中用于分组的字段名；未设置时按原列表逐项显示。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:10 packages/ui/src/components/select/types.ts
groupLabel	string | undefined	undefined	从每组首个选项读取分组标题的字段名；未设置或该字段缺失时使用 groupField 对应的分组值。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:11 packages/ui/src/components/select/types.ts
placeholder	string | undefined	undefined	尚未选择选项时显示的占位文字；未提供时使用当前语言的 select.placeholder 文案。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:12 packages/ui/src/components/select/types.ts
disabled	boolean | undefined	false	禁用选择器根状态以及默认触发器。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/select/Select.vue 解析值 false 来源 types.ts:13 packages/ui/src/components/select/types.ts
required	boolean | undefined	false	将选择器标记为必填；一体化触发器在 required 为真时不显示清除操作。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/select/Select.vue 解析值 false 来源 types.ts:14 packages/ui/src/components/select/types.ts
name	string | undefined	undefined	传递给 SelectRoot 的表单字段名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:15 packages/ui/src/components/select/types.ts
id	string | undefined	undefined	默认触发器的 DOM ID；自定义 trigger 插槽时由插槽内容自行提供 ID。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:16 packages/ui/src/components/select/types.ts
size	"default" | "lg" | "sm" | undefined	"default"	默认触发器的尺寸变体。
详情 声明类型 "default" | "lg" | "sm" | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 "default" 来源: packages/ui/src/components/select/Select.vue 解析值 "default" 来源 types.ts:17 packages/ui/src/components/select/types.ts
variant	"default" | "success" | "error" | undefined	"default"	默认触发器的边框及状态变体。
详情 声明类型 "default" | "success" | "error" | undefined 字面量 "default" "error" "success" 默认值详情 声明 "default" 来源: packages/ui/src/components/select/Select.vue 解析值 "default" 来源 types.ts:18 packages/ui/src/components/select/types.ts
errorMessage	string | undefined	undefined	传递给默认触发器的错误消息，用于错误提示语义。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:19 packages/ui/src/components/select/types.ts
clearable	boolean | undefined	false	允许默认触发器在有选中值时显示清除操作；required 为真时该操作被关闭。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/select/Select.vue 解析值 false 来源 types.ts:20 packages/ui/src/components/select/types.ts
position	"popper" | "item-aligned" | undefined	"popper"	设置选项浮层相对触发器的定位模式。
详情 声明类型 "popper" | "item-aligned" | undefined 字面量 "item-aligned" "popper" 默认值详情 声明 "popper" 来源: packages/ui/src/components/select/Select.vue 解析值 "popper" 来源 types.ts:21 packages/ui/src/components/select/types.ts
class	string | undefined	—	与 triggerClass 一起合并到默认触发器上的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 未声明默认值 — 来源 types.ts:22 packages/ui/src/components/select/types.ts
triggerClass	string | undefined	undefined	追加到默认触发器的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:23 packages/ui/src/components/select/types.ts
contentClass	string | undefined	undefined	追加到选项浮层的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/Select.vue 解析值 undefined 来源 types.ts:24 packages/ui/src/components/select/types.ts
itemVariant	"default" | "primary" | "secondary" | undefined	"default"	应用到 options 自动生成的每个 SelectItem 的变体。
详情 声明类型 "default" | "primary" | "secondary" | undefined 字面量 "default" "primary" "secondary" 默认值详情 声明 "default" 来源: packages/ui/src/components/select/Select.vue 解析值 "default" 来源 types.ts:25 packages/ui/src/components/select/types.ts
modelValue	string | undefined	—	当前选中的字符串值，通过 v-model 受控绑定；未选择时可为 undefined。
详情 声明类型 string | undefined 默认值详情 未声明默认值 — 来源 Select.vue packages/ui/src/components/select/Select.vue

Select — 事件

名称	签名或类型	说明
@update:modelValue	[value: string | undefined]	选择值变化时发出新值；在默认清除操作中发出 undefined。
详情 声明类型 [value: string | undefined] 来源 Select.vue packages/ui/src/components/select/Select.vue

Select — 插槽

名称	签名或类型	说明
#default	{}	接管整个 Select 内容。提供时组件不渲染默认触发器或由 options 生成的浮层，插槽需自行组合原语。
详情 声明类型 {} 来源 Select.vue packages/ui/src/components/select/Select.vue
#trigger	{}	替换默认触发器；选项浮层仍由 options 自动生成，插槽没有参数。
详情 声明类型 {} 来源 Select.vue packages/ui/src/components/select/Select.vue

SelectContent

SelectContent — 属性

名称	类型	默认值	说明
position	"popper" | "item-aligned" | undefined	"popper"	控制内容浮层相对触发器的定位方式。
详情 声明类型 "popper" | "item-aligned" | undefined 字面量 "item-aligned" "popper" 默认值详情 声明 'popper' 来源: packages/ui/src/components/select/SelectContent.vue 解析值 "popper" 来源 SelectContent.vue:18 packages/ui/src/components/select/SelectContent.vue
class	string | undefined	undefined	追加到浮动内容面板的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectContent.vue 解析值 undefined 来源 SelectContent.vue:19 packages/ui/src/components/select/SelectContent.vue

SelectContent — 插槽

名称	签名或类型	说明
#default	{}	渲染选项、分组和其他内容面板子项。
详情 声明类型 {} 来源 SelectContent.vue packages/ui/src/components/select/SelectContent.vue

SelectItem

SelectItem — 属性

名称	类型	默认值	说明
value 必填	string	—	此选项的非空唯一字符串值，用作选择结果。
详情 声明类型 string 默认值详情 未声明默认值 — 来源 SelectItem.vue:14 packages/ui/src/components/select/SelectItem.vue
disabled	boolean | undefined	false	阻止用户选择此选项。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/select/SelectItem.vue 解析值 false 来源 SelectItem.vue:15 packages/ui/src/components/select/SelectItem.vue
variant	"default" | "primary" | "secondary" | undefined	"default"	此选项的视觉变体。
详情 声明类型 NonNullable<"default" | "primary" | "secondary" | null | undefined> | undefined 字面量 "default" "primary" "secondary" 默认值详情 声明 'default' 来源: packages/ui/src/components/select/SelectItem.vue 解析值 "default" 来源 SelectItem.vue:16 packages/ui/src/components/select/SelectItem.vue
class	string | undefined	undefined	追加到选项根元素的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectItem.vue 解析值 undefined 来源 SelectItem.vue:17 packages/ui/src/components/select/SelectItem.vue
indicatorClass	string | undefined	undefined	追加到选中状态指示器的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectItem.vue 解析值 undefined 来源 SelectItem.vue:18 packages/ui/src/components/select/SelectItem.vue
iconClass	string | undefined	undefined	追加到选中勾选图标的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectItem.vue 解析值 undefined 来源 SelectItem.vue:19 packages/ui/src/components/select/SelectItem.vue
iconSize	IconSize | undefined	"md"	设置选中勾选图标的尺寸。
详情 声明类型 IconSize | undefined 字面量 "2xl" "lg" "md" "sm" "xl" "xs" 关联类型 IconSize 类型定义 — IconSize export type IconSize = NonNullable<VariantProps<typeof iconSizeVariants>['size']> 默认值详情 声明 'md' 来源: packages/ui/src/components/select/SelectItem.vue 解析值 "md" 来源 SelectItem.vue:20 packages/ui/src/components/select/SelectItem.vue

SelectItem — 插槽

名称	签名或类型	说明
#default	{}	显示在选项文字区域中的内容。
详情 声明类型 {} 来源 SelectItem.vue packages/ui/src/components/select/SelectItem.vue

SelectLabel

SelectLabel — 属性

名称	类型	默认值	说明
class	string | undefined	—	追加到分组标题元素的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 未声明默认值 — 来源 SelectLabel.vue:7 packages/ui/src/components/select/SelectLabel.vue

SelectLabel — 插槽

名称	签名或类型	说明
#default	{}	分组标题文本或其他标题内容。
详情 声明类型 {} 来源 SelectLabel.vue packages/ui/src/components/select/SelectLabel.vue

SelectScrollDownButton

SelectScrollDownButton — 属性

名称	类型	默认值	说明
class	string | undefined	undefined	追加到向下滚动提示控件的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectScrollDownButton.vue 解析值 undefined 来源 SelectScrollDownButton.vue:9 packages/ui/src/components/select/SelectScrollDownButton.vue
iconSize	IconSize | undefined	"md"	设置向下滚动箭头图标的尺寸。
详情 声明类型 IconSize | undefined 字面量 "2xl" "lg" "md" "sm" "xl" "xs" 关联类型 IconSize 类型定义 — IconSize export type IconSize = NonNullable<VariantProps<typeof iconSizeVariants>['size']> 默认值详情 声明 'md' 来源: packages/ui/src/components/select/SelectScrollDownButton.vue 解析值 "md" 来源 SelectScrollDownButton.vue:10 packages/ui/src/components/select/SelectScrollDownButton.vue

SelectScrollUpButton

SelectScrollUpButton — 属性

名称	类型	默认值	说明
class	string | undefined	undefined	追加到向上滚动提示控件的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectScrollUpButton.vue 解析值 undefined 来源 SelectScrollUpButton.vue:9 packages/ui/src/components/select/SelectScrollUpButton.vue
iconSize	IconSize | undefined	"md"	设置向上滚动箭头图标的尺寸。
详情 声明类型 IconSize | undefined 字面量 "2xl" "lg" "md" "sm" "xl" "xs" 关联类型 IconSize 类型定义 — IconSize export type IconSize = NonNullable<VariantProps<typeof iconSizeVariants>['size']> 默认值详情 声明 'md' 来源: packages/ui/src/components/select/SelectScrollUpButton.vue 解析值 "md" 来源 SelectScrollUpButton.vue:10 packages/ui/src/components/select/SelectScrollUpButton.vue

SelectSeparator

SelectSeparator — 属性

名称	类型	默认值	说明
decorative	boolean | undefined	true	声明分隔线是否仅用于装饰；装饰模式下由原语从无障碍树中隐藏。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/select/SelectSeparator.vue 解析值 true 来源 SelectSeparator.vue:7 packages/ui/src/components/select/SelectSeparator.vue
class	string | undefined	undefined	追加到分隔线元素的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectSeparator.vue 解析值 undefined 来源 SelectSeparator.vue:8 packages/ui/src/components/select/SelectSeparator.vue

SelectTrigger

SelectTrigger — 属性

名称	类型	默认值	说明
size	"default" | "lg" | "sm" | undefined	"default"	触发器的尺寸变体，同时决定下拉图标的尺寸映射。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 "default" 来源 SelectTrigger.vue:14 packages/ui/src/components/select/SelectTrigger.vue
variant	"default" | "error" | "success" | undefined	"default"	触发器的边框及状态变体。
详情 声明类型 NonNullable<"default" | "success" | "error" | null | undefined> | undefined 字面量 "default" "error" "success" 默认值详情 声明 'default' 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 "default" 来源 SelectTrigger.vue:15 packages/ui/src/components/select/SelectTrigger.vue
errorMessage	string | undefined	undefined	错误态消息，错误状态下用于关联触发器的错误提示。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 undefined 来源 SelectTrigger.vue:16 packages/ui/src/components/select/SelectTrigger.vue
disabled	boolean | undefined	false	禁用触发器和清除操作。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 false 来源 SelectTrigger.vue:17 packages/ui/src/components/select/SelectTrigger.vue
id	string | undefined	undefined	原生触发按钮的 DOM ID。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 undefined 来源 SelectTrigger.vue:18 packages/ui/src/components/select/SelectTrigger.vue
clearable	boolean | undefined	false	有选中值且未禁用时允许显示清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 false 来源 SelectTrigger.vue:20 packages/ui/src/components/select/SelectTrigger.vue
modelValue	unknown	undefined	当前值，仅用于判断是否存在可清除的选中内容。
详情 声明类型 unknown 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 undefined 来源 SelectTrigger.vue:22 packages/ui/src/components/select/SelectTrigger.vue
class	string | undefined	undefined	追加到触发按钮的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 undefined 来源 SelectTrigger.vue:23 packages/ui/src/components/select/SelectTrigger.vue
iconClass	string | undefined	undefined	追加到下拉指示图标的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/select/SelectTrigger.vue 解析值 undefined 来源 SelectTrigger.vue:24 packages/ui/src/components/select/SelectTrigger.vue

SelectTrigger — 事件

名称	签名或类型	说明
@clear	[]	用户执行清除操作时发出；该事件本身不承载参数。
详情 声明类型 [] 来源 SelectTrigger.vue packages/ui/src/components/select/SelectTrigger.vue

SelectTrigger — 插槽

名称	签名或类型	说明
#default	{}	触发器显示内容，通常包含 SelectValue。
详情 声明类型 {} 来源 SelectTrigger.vue packages/ui/src/components/select/SelectTrigger.vue

Reka UI 原语

一体化 Select 的公开属性、事件和插槽列在上方。使用原子组合时，SelectRoot、SelectValue 等无头原语由 reka-ui 提供，应从 reka-ui 直接导入；其余属性与插槽契约由 Reka UI 定义。

可访问性

• 键盘操作：支持 Space / Enter 打开下拉，Escape 关闭，方向键导航选项
• ARIA 属性：自动管理 aria-expanded、aria-haspopup、aria-activedescendant 等
• 焦点管理：打开时焦点锁定在下拉列表内，关闭时恢复焦点到触发器