Select 选择器

当选项过多时，使用下拉菜单展示并选择内容。

基础用法

请选择

选中: (未选)

vue

<my-select v-model="value" :options="options" placeholder="请选择" />

多选

multiple 属性开启多选模式。

多选城市

0 项

vue

<my-select v-model="value" :options="options" multiple placeholder="多选" />

带描述

每个选项支持 description 副标题。

上海

vue

const options = [
  { label: '北京', value: 'bj', description: '华北' },
  { label: '上海', value: 'sh', description: '华东' },
  { label: '广州', value: 'gz', description: '华南' },
]
<my-select v-model="value" :options="options" />

分区 / 分组

使用 groups 属性实现选项分组。

选择地区城市

(未选)

vue

const groups = [
  { label: '华北地区', options: [
    { label: '北京', value: 'bj' },
    { label: '天津', value: 'tj' },
  ]},
  { label: '华东地区', options: [
    { label: '上海', value: 'sh' },
    { label: '杭州', value: 'hz' },
  ]},
]
<my-select v-model="value" :groups="groups" />

禁用选项

在选项上设置 disabled: true。

有禁用项的列表

vue

const options = [
  { label: '可用', value: 'a' },
  { label: '禁用', value: 'b', disabled: true },
]
<my-select v-model="value" :options="options" />

自定义指示器

通过 #indicator 插槽替换选中标记。

上海

vue

<my-select v-model="value" :options="options">
  <template #indicator>
    <span style="color:#ee5a24;">✓</span>
  </template>
</my-select>

必填

*必填项

vue

<my-select v-model="value" :options="options" required placeholder="必填项" />

全宽

全宽选择器

vue

<my-select v-model="value" :options="options" full-width />

自定义展示 — 用户头像

每项配置 avatarUrl 头像地址，选项前显示真实头像，配合 description 展示邮箱等辅助信息。

请选择用户

选中: (未选)

vue

const options = [
  { label: 'Bob', value: '1', avatarUrl: 'https://...', description: 'bob@heroui.com' },
  { label: 'Fred', value: '2', avatarUrl: 'https://...', description: 'fred@heroui.com' },
]
<my-select v-model="value" :options="options" />

自定义展示 — Apple 渐变圆点

每项配置 gradient 渐变色数组，选项前显示渐变圆点，选中后也同步显示。

选个颜色

vue

// 每个选项自带渐变圆点
const options = [
  { label: '红色', value: 'red', gradient: ['#ff6b6b', '#ee5a24'] },
  { label: '橙色', value: 'orange', gradient: ['#feca57', '#ff9f43'] },
  { label: '绿色', value: 'green', gradient: ['#2ed573', '#7bed9f'] },
  { label: '蓝色', value: 'blue', gradient: ['#54a0ff', '#2e86de'] },
  { label: '紫色', value: 'purple', gradient: ['#a29bfe', '#6c5ce7'] },
  { label: '粉色', value: 'pink', gradient: ['#fd79a8', '#e84393'] },
]
<my-select v-model="value" :options="options" />

受控 / 受控多选

完全受控的 modelValue。

单选受控:

上海

多选受控:

北京上海

vue

<!-- 完全受控 -->
<my-select v-model="value" :options="options" />
<my-button @click="value = 'gz'">设为广州</my-button>

<!-- 多选受控 -->
<my-select v-model="value" :options="options" multiple />
<my-button @click="value = ['bj', 'sh']">设为京+沪</my-button>

受控展开状态

通过 visible + @update:visible 控制下拉展开。

上海

vue

<my-select
  v-model="value"
  :options="options"
  :visible="open"
  @update:visible="open = $event"
/>
<my-button @click="open = !open">切换</my-button>

异步加载

remote + remoteMethod + loading 实现远程搜索。

输入关键字搜索

vue

<my-select
  v-model="value"
  :options="remoteOptions"
  :loading="loading"
  :remote="true"
  :remote-method="handleSearch"
  filterable
  placeholder="输入关键字搜索"
/>

禁用状态

北京

北京上海

vue

<my-select v-model="value" :options="options" disabled />

组件结构

根元素 <div class="my-select"> 包含：触发器 __trigger（内部有必填星号 __star、多选标签 __tags 或单选值 __value、占位文字 __placeholder、后缀区 __suffix），以及下拉菜单 __dropdown（可选筛选框 __filter，以及分组 __group 或平铺选项 __option）。

CSS 类名

类名	说明
`.my-select`	根元素
`.is-full-width`	全宽模式
`.is-large`	大尺寸
`.is-small`	小尺寸
`.is-disabled`	禁用状态
`.is-active`	展开状态
`.is-multiple`	多选模式
`.is-loading`	加载状态
`.is-required`	必填状态
`.my-select__star`	必填星号
`.my-select__trigger`	触发器容器
`.my-select__placeholder`	占位文字
`.my-select__value`	单选选中值
`.my-select__tags`	多选标签列表
`.my-select__tag`	多选标签项
`.my-select__tag-close`	标签移除按钮
`.my-select__suffix`	后缀图标区
`.my-select__arrow`	下拉箭头
`.is-reverse`	箭头翻转（展开时）
`.my-select__clear`	清空按钮
`.my-select__loading`	加载旋转图标
`.my-select__dropdown`	下拉面板
`.my-select__filter`	筛选输入框容器
`.my-select__filter-input`	筛选输入框
`.my-select__group`	选项分组
`.my-select__group-label`	分组标题
`.my-select__option`	选项
`.is-selected`	已选中
`.my-select__option-content`	选项内容区
`.my-select__option-label`	选项文字
`.my-select__option-desc`	选项描述
`.my-select__avatar`	选项头像
`.my-select__dot`	选项渐变圆点
`.my-select__check`	选中标记对勾
`.my-select__empty`	空数据提示

API

属性	说明	类型	默认值
modelValue	绑定值	`string \| number \| (string \| number)[]`	—
options	选项列表	`SelectOption[]`	`[]`
groups	分组选项	`SelectGroup[]`	`[]`
placeholder	占位文字	`string`	`'请选择'`
multiple	是否多选	`boolean`	`false`
disabled	是否禁用	`boolean`	`false`
clearable	是否可清空	`boolean`	`false`
filterable	是否可筛选	`boolean`	`false`
required	是否必填	`boolean`	`false`
fullWidth	是否全宽	`boolean`	`false`
loading	是否加载中	`boolean`	`false`
remote	是否远程搜索	`boolean`	`false`
remoteMethod	远程搜索方法	`(query: string) => Promise<SelectOption[]>`	—
visible	受控展开状态	`boolean`	—
size	尺寸	`'large' \| 'default' \| 'small'`	`'default'`

interface SelectOption {
  label: string
  value: string | number
  disabled?: boolean
  description?: string       // 描述副标题
  gradient?: string[]        // 渐变圆点色值 ["#ff6b6b", "#ee5a24"]
  avatarUrl?: string         // 头像图片地址，优先级高于 gradient
  fallback?: string          // 头像加载失败时的备用文字（如首字母）
}

interface SelectGroup {
  label: string
  options: SelectOption[]
}

事件	说明
update:modelValue	值变更
change	选中值变更
visible-change	展开状态变更
remove-tag	多选标签移除
update:visible	受控展开

插槽	说明
indicator	自定义选中指示器

Select 选择器 ​

基础用法 ​

多选 ​

带描述 ​

分区 / 分组 ​

禁用选项 ​

自定义指示器 ​

必填 ​

全宽 ​

自定义展示 — 用户头像 ​

自定义展示 — Apple 渐变圆点 ​

受控 / 受控多选 ​

受控展开状态 ​

异步加载 ​

禁用状态 ​

组件结构 ​

CSS 类名 ​

API ​