Toggle Group 切换组
在一组互斥或可多选的切换项中管理一致的选择状态。
使用概览
适合使用
- 视图模式、对齐方式或筛选项需要成组切换时。
不建议使用
- 选项说明较长或数量过多而更适合选择菜单时。
真实示例
视图模式切换组
在列表与网格两种展示方式中单选。
正在加载示例…
安装
本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/toggle-group.json基础用法
导入
import { ToggleGroup, ToggleGroupItem } from "@richardqiu/quartz/toggle-group";JSX
<ToggleGroup type="single" defaultValue="grid" aria-label="视图模式"><ToggleGroupItem value="list">列表</ToggleGroupItem><ToggleGroupItem value="grid">网格</ToggleGroupItem></ToggleGroup>状态与控制摘要
默认
悬停
键盘焦点可见
激活
已禁用
已按下
label · textactive · booleanAPI 参考
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | "single" | "multiple" | "single" | 决定组内只能选择一项还是允许选择多项。 |
value | string | string[] | 未设置 | 受控提供当前选中的一个或多个项目值。 |
组合结构
- 01
ToggleGroup - 02
ToggleGroupItem
键盘约定
- Tab 进入或离开漫游焦点组，方向键移动焦点，Enter 或空格键更改当前项。
可访问性契约
- 为分组和每个项目提供清晰的可访问名称。
- 单项选择使用 single，彼此独立的多项选择使用 multiple。