Usage

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

Examples

Status: Not selected

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

@layer components {
  .toggle-button {
    @apply bg-purple-500 text-white;
  }

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

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

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

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)

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

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