MultiSelect 多选器
从可搜索候选列表中选择多个值，并以可移除标签展示结果。
使用概览
适合使用
- 团队、角色或分类允许多选且候选项数量较多时。
不建议使用
- 只能选择一个值，或选择顺序与重复次数具有业务含义时。
真实示例
负责团队多选
选择一个或多个团队并允许逐项移除。
正在加载示例…
安装
本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/multi-select.json基础用法
导入
import { MultiSelect } from "@richardqiu/quartz/multi-select";JSX
<MultiSelect aria-label="负责团队" emptyText="没有匹配团队" options={[{ label: "设计", value: "design" }, { label: "工程", value: "engineering" }]} defaultValue={["design"]} removeLabel={(label) => `移除 ${label}`} />状态与控制摘要
默认
键盘焦点可见
已打开
已选择
空状态
已禁用
label · textactive · booleanAPI 参考
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | readonly string[] | [] | 受控提供当前选择的所有候选值。 |
组合结构
- 01
MultiSelect
键盘约定
- 方向键浏览选项，Enter 选择；查询为空时 Backspace 移除最后一个值。
可访问性契约
- 每个已选值都要提供由使用方命名的移除按钮。
- 隐藏原生值只负责表单提交，不接管远程状态。