---
title: ToggleButton
description: An interactive toggle control for on/off or selected/unselected states
links:
  rac: ToggleButton
  source: toggle-button/toggle-button.tsx
  styles: toggle-button.css
  storybook: Components/Buttons/ToggleButton
  figma: true
---

## Usage

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

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

## Examples

### Variants

<ComponentPreview
  name="toggle-button-variants"
/>

### Icon Only

<ComponentPreview
  name="toggle-button-icon-only"
/>

### Sizes

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

### Disabled

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

### Controlled

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

## Customization

### Tailwind CSS

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

### Global CSS

To customize the ToggleButton 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 {
    @apply bg-purple-500 text-white;
  }

  .toggle-button--icon-only {
    @apply rounded-lg;
  }
}
```

## 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 ToggleButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button.css)):

#### Base & Size Classes [!toc]
- `.toggle-button` - Base toggle button styles
- `.toggle-button--sm` - Small size variant
- `.toggle-button--md` - Medium size variant (default)
- `.toggle-button--lg` - Large size variant

#### Variant Classes [!toc]
- `.toggle-button--default` - Default variant with filled background
- `.toggle-button--ghost` - Ghost variant with transparent background

#### Modifier Classes [!toc]
- `.toggle-button--icon-only` - Icon-only toggle button
- `.toggle-button--icon-only.toggle-button--sm` - Small icon-only
- `.toggle-button--icon-only.toggle-button--lg` - Large icon-only

### Interactive States

The toggle button supports both CSS pseudo-classes and data attributes for flexibility:

- **Selected**: `[data-selected="true"]` (accent background and foreground)
- **Hover**: `:hover` or `[data-hovered="true"]`
- **Active/Pressed**: `:active` or `[data-pressed="true"]` (includes scale transform)
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)

## API Reference

### ToggleButton

Inherits from [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'default' \| 'ghost'` | `'default'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the toggle button |
| `isIconOnly` | `boolean` | `false` | Whether the button contains only an icon |
| `isSelected` | `boolean` | - | Controlled selected state |
| `defaultSelected` | `boolean` | `false` | Default selected state (uncontrolled) |
| `isDisabled` | `boolean` | `false` | Whether the toggle button is disabled |
| `onChange` | `(isSelected: boolean) => void` | - | Handler called when selection changes |
| `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
| `children` | `React.ReactNode \| (values: ToggleButtonRenderProps) => React.ReactNode` | - | Button content or render prop |

### Render Props

When using the render prop pattern, these values are provided:

| Prop | Type | Description |
|------|------|-------------|
| `isSelected` | `boolean` | Whether the button is currently selected |
| `isPressed` | `boolean` | Whether the button is currently pressed |
| `isHovered` | `boolean` | Whether the button is hovered |
| `isFocused` | `boolean` | Whether the button is focused |
| `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
| `isDisabled` | `boolean` | Whether the button is disabled |

## Related Components

<RelatedComponents component="togglebutton" />
