# ToggleButtonGroup **Category**: react **URL**: https://www.heroui.com/docs/react/components/toggle-button-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/toggle-button-group.mdx > Groups multiple ToggleButtons into a unified control, allowing users to select one or multiple options. *** ## Import ```tsx import { ToggleButtonGroup, ToggleButton } from '@heroui/react'; ``` ### Usage ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Basic() { return ( ); } ``` ### Anatomy Import the ToggleButtonGroup component and access all parts using dot notation. ```tsx import { ToggleButtonGroup, ToggleButton } from '@heroui/react'; export default () => ( First Second Third ); ``` ### Sizes ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Sizes() { return (
Small
Medium (default)
Large
); } ``` ### Orientation ```tsx import {Bold, Italic, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Orientation() { return (
Horizontal
Vertical
); } ``` ### Detached Use `isDetached` to separate buttons with gaps instead of connecting them. ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Attached() { return (
Attached (default)
Detached
); } ``` ### Full Width ```tsx import { Bold, Italic, Strikethrough, TextAlignCenter, TextAlignLeft, TextAlignRight, Underline, } from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function FullWidth() { return (
Left Center Right
); } ``` ### Selection Mode Use `selectionMode="single"` for mutually exclusive choices or `selectionMode="multiple"` for independent toggles. ```tsx import { Bold, Italic, Strikethrough, TextAlignCenter, TextAlignLeft, TextAlignRight, Underline, } from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function SelectionMode() { return (
Single selection Left Center Right
Multiple selection
); } ``` ### Controlled ```tsx "use client"; import type {Key} from "@heroui/react"; import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [selectedKeys, setSelectedKeys] = useState(new Set(["bold"])); return (

Selected:{" "} {selectedKeys.size > 0 ? [...selectedKeys].join(", ") : "None"}

); } ``` ### Disabled ```tsx import {Bold, Italic, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Disabled() { return (
All buttons disabled
Individual button disabled
); } ``` ### Without Separator Simply omit the `` component from your buttons. ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function WithoutSeparator() { return ( ); } ``` ## Related Components - **ToggleButton**: Interactive toggle control for on/off states - **ButtonGroup**: Group related buttons together - **Button**: Allows a user to perform an action ## Styling ### Passing Tailwind CSS classes ```tsx import { ToggleButtonGroup, ToggleButton } from '@heroui/react'; function CustomToggleButtonGroup() { return ( Option A Option B ); } ``` ### Customizing the component classes To customize the ToggleButtonGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .toggle-button-group { @apply rounded-lg; } .toggle-button-group__separator { @apply opacity-25; } .toggle-button-group--full-width { @apply w-full; } } ``` HeroUI follows the [BEM](https://getbem.com/) 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](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button-group.css)): #### 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](https://react-aria.adobe.com/ToggleButtonGroup). | Prop | Type | Default | Description | |------|------|---------|-------------| | `selectionMode` | `"single" \| "multiple"` | `"single"` | Whether one or multiple buttons can be selected | | `selectedKeys` | `Iterable` | - | Controlled selection state | | `defaultSelectedKeys` | `Iterable` | - | Default selected keys (uncontrolled) | | `onSelectionChange` | `(keys: Set) => void` | - | Called when selection changes | | `disallowEmptySelection` | `boolean` | `false` | Prevents clearing all selections | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size propagated to child ToggleButtons | | `isDetached` | `boolean` | `false` | Whether buttons are visually separated with gaps | | `fullWidth` | `boolean` | `false` | Whether the group fills available width | | `isDisabled` | `boolean` | `false` | Disables all buttons in the group | | `className` | `string` | - | Additional CSS classes | ### ToggleButtonGroup.Separator Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `className` | `string` | - | Additional CSS classes | ### 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 `` inside each ToggleButton (except the first) to show dividers between buttons - Use `disallowEmptySelection` with `selectionMode="single"` to ensure one option is always selected