ToggleButton - Heroui

Import

tsx

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

Usage

Variants

Icon Only

Sizes

Controlled

Disabled

Styling

Passing Tailwind CSS classes

tsx

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

function CustomToggleButton() {
  return (
    <ToggleButton className="bg-purple-500 text-white">
      Toggle
    </ToggleButton>
  );
}

Customizing the component classes

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

Learn more.

css

@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.

CSS Classes

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

Base & Size Classes

.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

.toggle-button--default - Default variant with filled background
.toggle-button--ghost - Ghost variant with transparent background

Modifier Classes

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

Inherits from React Aria ToggleButton.

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

ToggleButtonRenderProps

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