Usage

import { ToggleButtonGroup, ToggleButton } from '@heroui/react';

Anatomy

import { ToggleButtonGroup, ToggleButton } from '@heroui/react';

export default () => (
  <ToggleButtonGroup selectionMode="multiple">
    <ToggleButton id="first">First</ToggleButton>
    <ToggleButton id="second">
      <ToggleButtonGroup.Separator />
      Second
    </ToggleButton>
    <ToggleButton id="third">
      <ToggleButtonGroup.Separator />
      Third
    </ToggleButton>
  </ToggleButtonGroup>
);

Examples

Sizes

Small

Medium (default)

Large

Orientation

Horizontal

Vertical

Full Width

Disabled

All buttons disabled

Individual button disabled

Without Separator

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

Detached

Use isDetached to separate buttons with gaps instead of connecting them.

Attached (default)

Detached

Selection Mode

Use selectionMode="single" for mutually exclusive choices or selectionMode="multiple" for independent toggles.

Single selection

Multiple selection

Controlled

Selected: bold

Customization

Tailwind CSS

Global CSS

To customize the ToggleButtonGroup component classes, you can use the @layer components directive. Learn more.

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

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

  .toggle-button-group--full-width {
    @apply w-full;
  }
}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The ToggleButtonGroup component uses these CSS classes (View source styles):

Base & Layout Classes

.toggle-button-group - Base container styles
.toggle-button-group--horizontal - Horizontal orientation
.toggle-button-group--vertical - Vertical orientation
.toggle-button-group--full-width - Full width modifier
.toggle-button-group__separator - Separator element between buttons

Modifier Classes

.toggle-button-group--detached - Detached mode (separated buttons with gaps)

API Reference

ToggleButtonGroup

Inherits from React Aria ToggleButtonGroup.

Prop	Type	Default	Description
`selectionMode`	`"single" \| "multiple"`	`"single"`	Whether one or multiple buttons can be selected
`selectedKeys`	`Iterable<Key>`	-	Controlled selection state
`defaultSelectedKeys`	`Iterable<Key>`	-	Default selected keys (uncontrolled)
`onSelectionChange`	`(keys: Set<Key>) => void`	-	Called when selection changes
`disallowEmptySelection`	`boolean`	`false`	Prevents clearing all selections
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout direction
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Size propagated to child ToggleButtons
`isDetached`	`boolean`	`false`	Whether buttons are visually separated with gaps
`fullWidth`	`boolean`	`false`	Whether the group fills available width
`isDisabled`	`boolean`	`false`	Disables all buttons in the group
`className`	`string`	-	Additional CSS classes

ToggleButtonGroup.Separator

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

Note

ToggleButtonGroup uses React Context to pass size to all child ToggleButton components
Each ToggleButton must have a unique id prop that corresponds to the keys used in selectedKeys / defaultSelectedKeys
The isDisabled prop is handled natively by React Aria and disables all child ToggleButtons — individual buttons can override this by setting isDisabled={false}
The component automatically handles border radius between buttons
Add <ToggleButtonGroup.Separator /> inside each ToggleButton (except the first) to show dividers between buttons
Use disallowEmptySelection with selectionMode="single" to ensure one option is always selected

ToggleButton

ButtonGroup

Button

ToggleButtonGroup

On this page