---
title: ToggleButtonGroup
description: Groups multiple ToggleButtons into a unified control, allowing users to select one or multiple options.
links:
  rac: ToggleButtonGroup
  source: toggle-button-group/toggle-button-group.tsx
  styles: toggle-button-group.css
  storybook: Components/Buttons/ToggleButtonGroup
  figma: true
---

## Usage

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

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

## Anatomy

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

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

### Orientation

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

### Full Width

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

### Disabled

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

### Without Separator

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

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

### Detached

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

<ComponentPreview
  name="toggle-button-group-attached"
/>

### Selection Mode

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

<ComponentPreview
  name="toggle-button-group-selection-mode"
/>

### Controlled

<ComponentPreview
  name="toggle-button-group-controlled"
/>

## Customization

### Tailwind CSS

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

### Global CSS

To customize the ToggleButtonGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@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](https://getbem.com/) 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](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button-group.css)):

#### Base & Layout Classes [!toc]
- `.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 [!toc]
- `.toggle-button-group--detached` - Detached mode (separated buttons with gaps)

## API Reference

### ToggleButtonGroup

Inherits from [React Aria ToggleButtonGroup](https://react-aria.adobe.com/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

## Related Components

<RelatedComponents component="toggle-button-group" />
