---
title: ButtonGroup 按钮组
description: 将相关按钮组合在一起，保持一致的样式与间距
links:
  rac: Button
  source: button-group/button-group.tsx
  styles: button-group.css
  storybook: Components/Buttons/ButtonGroup
  figma: true
---

## 用法

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

<ComponentPreview
  name="button-group-basic"
/>

## 组件结构

```tsx
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` 属性。

## 示例

### 变体

<ComponentPreview
  name="button-group-variants"
/>

### 尺寸

<ComponentPreview
  name="button-group-sizes"
/>

### 方向

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

<ComponentPreview
  name="button-group-orientation"
/>

### 带图标

<ComponentPreview
  name="button-group-with-icons"
/>

### 宽度充满

<ComponentPreview
  name="button-group-full-width"
/>

### 禁用状态

<ComponentPreview
  name="button-group-disabled"
/>

### 无分隔线

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

<ComponentPreview
  name="button-group-without-separator"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="button-group-custom-styles" />

### 全局 CSS

可使用 `@layer components` 指令自定义 ButtonGroup 组件类。
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

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

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

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

ButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)）：

#### 基础类 [!toc]
- `.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 缩放变换，外观更统一

## 相关组件

<RelatedComponents component="button-group" />
