ToggleButtonGroup 切换按钮组
将多个 ToggleButton 组合为统一控件，允许用户选择单个或多个选项。
引入
import { ToggleButtonGroup, ToggleButton } from '@heroui/react';用法
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Basic() {
return (组件结构
导入 ToggleButtonGroup 组件，并通过点语法访问所有子部分。
import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
export default () => (
<ToggleButtonGroup selectionMode="multiple">
<ToggleButton id="first">First</ToggleButton>
<ToggleButton id="second">
<ToggleButtonGroup.Separator />
Second
</ToggleButton>
<ToggleButton id="third">
<ToggleButtonGroup.Separator />
Third
</ToggleButton>
</ToggleButtonGroup>
);尺寸
小
中（默认）
大
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Sizes() {
return (方向
水平
垂直
import {Bold, Italic, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Orientation() {
return (分离模式
使用 isDetached 让按钮之间留出间隔，而不是彼此连接。
附着（默认）
分离
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Attached() {
return (全宽
import {
Bold,
Italic,
Strikethrough,
TextAlignCenter,选择模式
使用 selectionMode="single" 实现互斥选择，或使用 selectionMode="multiple" 实现独立切换。
单选
多选
import {
Bold,
Italic,
Strikethrough,
TextAlignCenter,受控
已选：bold
"use client";
import type {Key} from "@heroui/react";
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";禁用
全部按钮已禁用
单个按钮已禁用
import {Bold, Italic, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function Disabled() {
return (无分隔线
在按钮中直接省略 <ToggleButtonGroup.Separator /> 组件即可。
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";
export function WithoutSeparator() {
return (样式
传入 Tailwind CSS 类
import { ToggleButtonGroup, ToggleButton } from '@heroui/react';
function CustomToggleButtonGroup() {
return (
<ToggleButtonGroup className="bg-purple-100" selectionMode="single">
<ToggleButton id="a">Option A</ToggleButton>
<ToggleButton id="b">
<ToggleButtonGroup.Separator />
Option B
</ToggleButton>
</ToggleButtonGroup>
);
}自定义组件类
若要自定义 ToggleButtonGroup 组件类，可以使用 @layer components 指令。
了解更多.
@layer components {
.toggle-button-group {
@apply rounded-lg;
}
.toggle-button-group__separator {
@apply opacity-25;
}
.toggle-button-group--full-width {
@apply w-full;
}
}HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。
CSS 类
ToggleButtonGroup 组件使用以下 CSS 类（查看源码样式）：
基础与布局类
.toggle-button-group- 容器基础样式.toggle-button-group--horizontal- 水平方向.toggle-button-group--vertical- 垂直方向.toggle-button-group--full-width- 全宽修饰符.toggle-button-group__separator- 按钮之间的分隔线元素
修饰符类
.toggle-button-group--detached- 分离模式（按钮间有间隔）
API 参考
ToggleButtonGroup Props
继承自 React Aria ToggleButtonGroup。
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
selectionMode | "single" | "multiple" | "single" | 是否允许选中一个或多个按钮 |
selectedKeys | Iterable<Key> | - | 受控的选中状态 |
defaultSelectedKeys | Iterable<Key> | - | 默认选中 key（非受控） |
onSelectionChange | (keys: Set<Key>) => void | - | 选中变化时调用 |
disallowEmptySelection | boolean | false | 是否禁止清空所有选中 |
orientation | "horizontal" | "vertical" | "horizontal" | 布局方向 |
size | "sm" | "md" | "lg" | "md" | 传递给子 ToggleButton 的尺寸 |
isDetached | boolean | false | 按钮是否以间隔分离显示 |
fullWidth | boolean | false | 按钮组是否占满可用宽度 |
isDisabled | boolean | false | 是否禁用组内全部按钮 |
className | string | - | 额外的 CSS 类 |
ToggleButtonGroup.Separator Props
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
className | string | - | 额外的 CSS 类 |
说明
- ToggleButtonGroup 使用 React Context 将
size传递给所有子 ToggleButton 组件 - 每个 ToggleButton 都必须有唯一
idprop，并与selectedKeys/defaultSelectedKeys中使用的 key 对应 isDisabledprop 由 React Aria 原生处理，会禁用所有子 ToggleButton；单个按钮可通过设置isDisabled={false}覆盖- 组件会自动处理按钮之间的圆角
- 在每个 ToggleButton（第一个除外）内添加
<ToggleButtonGroup.Separator />，可在按钮之间显示分隔线 - 将
disallowEmptySelection与selectionMode="single"一起使用，可确保始终有一个选项被选中
