ButtonGroup - Heroui

Import

tsx

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

Usage

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

Sizes

Orientation

Use the orientation prop to arrange buttons horizontally or vertically.

With Icons

Full Width

Disabled State

Without Separator

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

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.

css

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

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

HeroUI follows the BEM 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):

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 <ButtonGroup.Separator /> 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 <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