Completeness: behavior-required

The stylesheet is only the visible half of this component. It also needs a keyboard map, focus managed across more than one element, ARIA attributes that point at other nodes, and [data-*] attributes that only running code sets — so a CSS-only port will not reproduce it. Use @blakeui/react, or read the interaction contract from the MCP server with get_component_behavior("ToggleButton") and build the behaviour yourself.

Import

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

Usage

import {ToggleButton} from "@blakeui/react";
import {Heart} from "@gravity-ui/icons";

export function Basic() {
  return (

Variants

import {ToggleButton} from "@blakeui/react";
import {Heart} from "@gravity-ui/icons";

export function Variants() {
  return (

Icon Only

import {ToggleButton} from "@blakeui/react";
import {Bookmark, Heart} from "@gravity-ui/icons";

export function IconOnly() {
  return (

Sizes

import {ToggleButton} from "@blakeui/react";
import {Heart} from "@gravity-ui/icons";

export function Sizes() {
  return (

Controlled

Status: Not selected

"use client";

import {ToggleButton} from "@blakeui/react";
import {Heart, HeartFill} from "@gravity-ui/icons";
import {useState} from "react";

Disabled

import {ToggleButton} from "@blakeui/react";
import {Heart, HeartFill} from "@gravity-ui/icons";

export function Disabled() {
  return (

Related Components

Button

Switch

Checkbox

Styling

Passing Tailwind CSS classes

import { ToggleButton } from '@blakeui/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.

A worked example is in Styling.

blakeUI 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

ToggleButton

Related Components

On this page

Related Components