ToggleButton

Import

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

Usage

Variants

Icon Only

Sizes

Controlled

Disabled

Styling

Passing Tailwind CSS classes

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.

@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