---
title: ButtonGroup
description: Group related buttons together with consistent styling and spacing
links:
  rac: Button
  source: button-group/button-group.tsx
  styles: button-group.css
  storybook: Components/Buttons/ButtonGroup
  figma: true
---

## Usage

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

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

## Anatomy

```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** wraps multiple Button components together, applying consistent styling, spacing, and automatic border radius handling. It uses React Context to pass `size`, `variant`, and `isDisabled` props to all child buttons.

## Examples

### Variants

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

### Sizes

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

### Orientation

Use the `orientation` prop to arrange buttons horizontally or vertically.

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

### With Icons

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

### Full Width

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

### Disabled State

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

### Without Separator

Simply omit the `<ButtonGroup.Separator />` component from your buttons.

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

## Customization

### Tailwind CSS

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

### Global CSS

To customize the ButtonGroup component classes, you can use the `@layer components` directive.
[Learn more](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;
  }
}
```

## Styling Reference

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)):

#### Base Classes [!toc]
- `.button-group` - Base button group container
- `.button-group--full-width` - Full width modifier
- `.button-group__separator` - Separator element between buttons

The ButtonGroup component automatically applies border radius to buttons:
- First button gets rounded left/start edge
- Last button gets rounded right/end edge
- Middle buttons have no border radius
- Single button gets full border radius on all edges

Add `<ButtonGroup.Separator />` inside each Button (except the first) to show dividers between buttons.

## API Reference

### ButtonGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | Visual style variant applied to all buttons in the group |
| `size` | `'sm' \| 'md' \| 'lg'` | - | Size applied to all buttons in the group |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the button group |
| `fullWidth` | `boolean` | `false` | Whether the button group should take full width of its container |
| `isDisabled` | `boolean` | `false` | Whether all buttons in the group are disabled (can be overridden on individual buttons) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Button components to group together |

### ButtonGroup.Separator

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |

## Note

- ButtonGroup uses React Context to pass `size`, `variant`, and `isDisabled` props to all child Button components
- **Only direct child buttons receive the ButtonGroup props** - Buttons nested inside other components (like Modal, Dropdown, etc.) will not inherit the group's props even if they are descendants of the ButtonGroup
- Individual Button components can override the group's `isDisabled` prop by setting `isDisabled={false}`
- The component automatically handles border radius between buttons
- Add `<ButtonGroup.Separator />` inside each Button (except the first) to show dividers between buttons
- Buttons in a group have their active/pressed scale transform removed for a more cohesive appearance

## Related Components

<RelatedComponents component="button-group" />
