用法

import { ButtonGroup, Button } from '@heroui/react';

组件结构

import { ButtonGroup, Button } from '@heroui/react';

export default () => (
  <ButtonGroup>
    <Button>First</Button>
    <Button>
      <ButtonGroup.Separator />
      Second
    </Button>
    <Button>
      <ButtonGroup.Separator />
      Third
    </Button>
  </ButtonGroup>
);

ButtonGroup 将多个 Button 组合在一起，应用一致的样式、间距与自动圆角处理。它通过 React Context 向所有子按钮传递 size、variant 与 isDisabled 属性。

示例

变体

主要

次要

第三

线框

幽灵

危险

尺寸

小

中（默认）

大

方向

使用 orientation 属性可水平或垂直排列按钮。

横向

纵向

带图标

仅图标按钮

宽度充满

禁用状态

全部禁用

组已禁用，但单个按钮可覆盖

无分隔线

省略按钮中的 <ButtonGroup.Separator /> 组件即可。

自定义样式

Tailwind CSS

全局 CSS

可使用 @layer components 指令自定义 ButtonGroup 组件类。了解更多。

@layer components {
  .button-group {
    @apply gap-2 rounded-lg;
  }

  .button-group__separator {
    @apply opacity-25;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

ButtonGroup 组件使用以下 CSS 类（查看源码样式）：

基础类

.button-group - 按钮组根容器
.button-group--full-width - 全宽修饰符
.button-group__separator - 按钮之间的分隔元素

ButtonGroup 组件自动为按钮应用圆角：

第一个按钮圆角左/起始边
最后一个按钮圆角右/结束边
中间按钮无圆角
单个按钮四边全圆角

在每个 Button 内（第一个除外）添加 <ButtonGroup.Separator /> 以显示分隔线。

API 参考

ButtonGroup

Prop	类型	默认值	描述
`variant`	`'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'`	-	应用于组内所有按钮的视觉变体
`size`	`'sm' \| 'md' \| 'lg'`	-	应用于组内所有按钮的尺寸
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	按钮组方向
`fullWidth`	`boolean`	`false`	是否占满容器宽度
`isDisabled`	`boolean`	`false`	是否禁用组内所有按钮（单个按钮可覆盖）
`className`	`string`	-	附加 CSS 类
`children`	`React.ReactNode`	-	要组合的 Button 组件

ButtonGroup.Separator

Prop	类型	默认值	描述
`className`	`string`	-	附加 CSS 类

说明

ButtonGroup 通过 React Context 向所有子 Button 传递 size、variant 与 isDisabled 属性
仅直接子按钮接收 ButtonGroup 属性 - 嵌套在其他组件（如 Modal、Dropdown 等）内的 Button 即使位于 ButtonGroup 后代也不会继承组属性
单个 Button 可通过 isDisabled={false} 覆盖组的 isDisabled 属性
组件自动处理按钮之间的圆角
在每个 Button 内（第一个除外）添加 <ButtonGroup.Separator /> 以显示分隔线
组内按钮移除 active/pressed 缩放变换，外观更统一