# ToggleButtonGroup · HeroUI

> Groups multiple ToggleButtons into a unified control, allowing users to select one or multiple options.

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

## Import

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

### Usage


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


### Anatomy

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

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

### Sizes


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


### Orientation


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


### Detached

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


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


### Full Width


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


### Selection Mode

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


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


### Controlled


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


### Disabled


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


### Without Separator

Simply omit the `` component from your buttons.


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


## Styling

### Passing Tailwind CSS classes

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

function CustomToggleButtonGroup() {
  return (
    <ToggleButtonGroup className="bg-purple-100" selectionMode="single">
      <ToggleButton id="a">Option A</ToggleButton>
      <ToggleButton id="b">
        <ToggleButtonGroup.Separator />
        Option B
      </ToggleButton>
    </ToggleButtonGroup>
  );
}
```

### Customizing the component classes

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

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

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` | - | Controlled selection state |
| `defaultSelectedKeys` | `Iterable` | - | Default selected keys (uncontrolled) |
| `onSelectionChange` | `(keys: Set) => 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 Props

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

### Notes

- 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 `` inside each ToggleButton (except the first) to show dividers between buttons
- Use `disallowEmptySelection` with `selectionMode="single"` to ensure one option is always selected

---

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