# ButtonGroup · HeroUI

> Group related buttons together with consistent styling and spacing

- Page: https://jiguang132.com/systems/heroui/docs/components/button-group
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

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

### Usage


> Example `button-group-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


### Anatomy

Import the ButtonGroup component and access all parts using dot notation.

```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.

### Variants


> Example `button-group-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


### Sizes


> Example `button-group-sizes`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


### Orientation

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


> Example `button-group-orientation`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


### With Icons


> Example `button-group-with-icons`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


### Full Width


> Example `button-group-full-width`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


### Disabled State


> Example `button-group-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


### Without Separator

Simply omit the `` component from your buttons.


> Example `button-group-without-separator`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/button-group


## Styling

### Passing Tailwind CSS classes

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

function CustomButtonGroup() {
  return (
    <ButtonGroup className="gap-2">
      <Button>First</Button>
      <Button>
        <ButtonGroup.Separator />
        Second
      </Button>
      <Button>
        <ButtonGroup.Separator />
        Third
      </Button>
    </ButtonGroup>
  );
}
```

### Customizing the component classes

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;
  }
}
```

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
- `.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 `` inside each Button (except the first) to show dividers between buttons.

## API Reference

### ButtonGroup Props

| 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 Props

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

### Notes

- 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 `` 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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt