ToggleButtonGroup

Import

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

Usage

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";

export function Basic() {
  return (

Anatomy

Import the ToggleButtonGroup component and access all parts using dot notation.

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

export default () => (
  <ToggleButtonGroup selectionMode="multiple">
    <ToggleButton id="first">First</ToggleButton>
    <ToggleButton id="second">
      <ToggleButtonGroup.Separator />
      Second
    </ToggleButton>
    <ToggleButton id="third">
      <ToggleButtonGroup.Separator />
      Third
    </ToggleButton>
  </ToggleButtonGroup>
);

Sizes

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";

export function Sizes() {
  return (

Orientation

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {Bold, Italic, Underline} from "@gravity-ui/icons";

export function Orientation() {
  return (

Detached

Use isDetached to separate buttons with gaps instead of connecting them.

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";

export function Attached() {
  return (

Full Width

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {
  Bold,
  Italic,
  Strikethrough,

Selection Mode

Use selectionMode="single" for mutually exclusive choices or selectionMode="multiple" for independent toggles.

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {
  Bold,
  Italic,
  Strikethrough,

Controlled

"use client";

import type {Key} from "@blakeui/react";

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";

Disabled

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {Bold, Italic, Underline} from "@gravity-ui/icons";

export function Disabled() {
  return (

Without Separator

Simply omit the <ToggleButtonGroup.Separator /> component from your buttons.

import {ToggleButton, ToggleButtonGroup} from "@blakeui/react";
import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";

export function WithoutSeparator() {
  return (

Styling

Passing Tailwind CSS classes

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

function CustomToggleButtonGroup() {
  return (
    <ToggleButtonGroup className="bg-purple-100" selectionMode="single">
      <ToggleButton id="a">Option A</ToggleButton>
      <ToggleButton id="b">
        <ToggleButtonGroup.Separator />
        Option B
      </ToggleButton>
    </ToggleButtonGroup>
  );
}

Customizing the component classes

To customize the ToggleButtonGroup 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 ToggleButtonGroup component uses these CSS classes (View source styles):

Base & Layout Classes

• .toggle-button-group - Base container styles
• .toggle-button-group--horizontal - Horizontal orientation
• .toggle-button-group--vertical - Vertical orientation
• .toggle-button-group--full-width - Full width modifier
• .toggle-button-group__separator - Separator element between buttons

Modifier Classes

• .toggle-button-group--detached - Detached mode (separated buttons with gaps)

API Reference

ToggleButtonGroup Props

Inherits from React Aria ToggleButtonGroup.

ToggleButtonGroup.Separator Props

Notes

• ToggleButtonGroup uses React Context to pass size to all child ToggleButton components
• Each ToggleButton must have a unique id prop that corresponds to the keys used in selectedKeys / defaultSelectedKeys
• The isDisabled prop is handled natively by React Aria and disables all child ToggleButtons — individual buttons can override this by setting isDisabled={false}
• The component automatically handles border radius between buttons
• Add <ToggleButtonGroup.Separator /> inside each ToggleButton (except the first) to show dividers between buttons
• Use disallowEmptySelection with selectionMode="single" to ensure one option is always selected