Toggle Button Group

A toggle button group allows a user to toggle a selection of items, for example a set of formatting options.

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"

import {
  ToggleButtonGroup,
  ToggleButtonGroupItem,
} from "@/components/ui/toggle-button-group"

export function ToggleButtonGroupDemo() {
  return (
    <ToggleButtonGroup variant="outline" aria-label="Text formatting">
      <ToggleButtonGroupItem aria-label="Toggle bold">
        <BoldIcon />
      </ToggleButtonGroupItem>
      <ToggleButtonGroupItem aria-label="Toggle italic">
        <ItalicIcon />
      </ToggleButtonGroupItem>
      <ToggleButtonGroupItem aria-label="Toggle underline">
        <UnderlineIcon />
      </ToggleButtonGroupItem>
    </ToggleButtonGroup>
  )
}

Installation

CLI

Manual


pnpm
npm
yarn
bun
pnpm dlx shadcn@latest add toggle-button-group

Usage

import {
  ToggleButtonGroup,
  ToggleButtonGroupItem,
} from "@/components/ui/toggle-button-group"

<ToggleButtonGroup aria-label="Text formatting">
  <ToggleButtonGroupItem aria-label="Toggle bold">
    <BoldIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle underline">
    <UnderlineIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>

Features

A toggle button group is a set of toggle buttons that are visually grouped together. They are commonly used for formatting toolbars and similar use cases where multiple related toggles are presented together.

Flexible – Each button in the group can be independently toggled on or off.
Styleable – Supports both default and outline variants with multiple size options.
Accessible – Each toggle button has proper ARIA attributes and keyboard support.
Consistent styling – Buttons in the group are visually connected with shared borders.

Examples

Default

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"

import {
  ToggleButtonGroup,
  ToggleButtonGroupItem,
} from "@/components/ui/toggle-button-group"

export function ToggleButtonGroupDefault() {
  return (
    <ToggleButtonGroup aria-label="Text formatting">
      <ToggleButtonGroupItem aria-label="Toggle bold">
        <BoldIcon />
      </ToggleButtonGroupItem>
      <ToggleButtonGroupItem aria-label="Toggle italic">
        <ItalicIcon />
      </ToggleButtonGroupItem>
      <ToggleButtonGroupItem aria-label="Toggle underline">
        <UnderlineIcon />
      </ToggleButtonGroupItem>
    </ToggleButtonGroup>
  )
}

<ToggleButtonGroup aria-label="Text formatting">
  <ToggleButtonGroupItem aria-label="Toggle bold">
    <BoldIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle underline">
    <UnderlineIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>

Outline

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"

import {
  ToggleButtonGroup,
  ToggleButtonGroupItem,
} from "@/components/ui/toggle-button-group"

export function ToggleButtonGroupDemo() {
  return (
    <ToggleButtonGroup variant="outline" aria-label="Text formatting">
      <ToggleButtonGroupItem aria-label="Toggle bold">
        <BoldIcon />
      </ToggleButtonGroupItem>
      <ToggleButtonGroupItem aria-label="Toggle italic">
        <ItalicIcon />
      </ToggleButtonGroupItem>
      <ToggleButtonGroupItem aria-label="Toggle underline">
        <UnderlineIcon />
      </ToggleButtonGroupItem>
    </ToggleButtonGroup>
  )
}

<ToggleButtonGroup variant="outline" aria-label="Text formatting">
  <ToggleButtonGroupItem aria-label="Toggle bold">
    <BoldIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle underline">
    <UnderlineIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>

Size

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"

import {
  ToggleButtonGroup,
  ToggleButtonGroupItem,
} from "@/components/ui/toggle-button-group"

export function ToggleButtonGroupSize() {
  return (
    <div className="flex flex-col gap-4">
      <ToggleButtonGroup
        variant="outline"
        size="sm"
        aria-label="Text formatting"
      >
        <ToggleButtonGroupItem aria-label="Toggle bold">
          <BoldIcon />
        </ToggleButtonGroupItem>
        <ToggleButtonGroupItem aria-label="Toggle italic">
          <ItalicIcon />
        </ToggleButtonGroupItem>
        <ToggleButtonGroupItem aria-label="Toggle underline">
          <UnderlineIcon />
        </ToggleButtonGroupItem>
      </ToggleButtonGroup>

      <ToggleButtonGroup variant="outline" aria-label="Text formatting">
        <ToggleButtonGroupItem aria-label="Toggle bold">
          <BoldIcon />
        </ToggleButtonGroupItem>
        <ToggleButtonGroupItem aria-label="Toggle italic">
          <ItalicIcon />
        </ToggleButtonGroupItem>
        <ToggleButtonGroupItem aria-label="Toggle underline">
          <UnderlineIcon />
        </ToggleButtonGroupItem>
      </ToggleButtonGroup>

      <ToggleButtonGroup
        variant="outline"
        size="lg"
        aria-label="Text formatting"
      >
        <ToggleButtonGroupItem aria-label="Toggle bold">
          <BoldIcon />
        </ToggleButtonGroupItem>
        <ToggleButtonGroupItem aria-label="Toggle italic">
          <ItalicIcon />
        </ToggleButtonGroupItem>
        <ToggleButtonGroupItem aria-label="Toggle underline">
          <UnderlineIcon />
        </ToggleButtonGroupItem>
      </ToggleButtonGroup>
    </div>
  )
}

// Small
<ToggleButtonGroup variant="outline" size="sm" aria-label="Text formatting">
  <ToggleButtonGroupItem aria-label="Toggle bold">
    <BoldIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle underline">
    <UnderlineIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>
 
// Default
<ToggleButtonGroup variant="outline" aria-label="Text formatting">
  <ToggleButtonGroupItem aria-label="Toggle bold">
    <BoldIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle underline">
    <UnderlineIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>
 
// Large
<ToggleButtonGroup variant="outline" size="lg" aria-label="Text formatting">
  <ToggleButtonGroupItem aria-label="Toggle bold">
    <BoldIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle underline">
    <UnderlineIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>

API Reference

ToggleButtonGroup

The ToggleButtonGroup component serves as a container for grouping multiple toggle buttons together.

Prop	Type	Default	Description
`variant`	`"default" \| "outline"`	`"default"`	The visual style applied to all buttons in the group.
`size`	`"default" \| "sm" \| "lg"`	`"default"`	The size applied to all buttons in the group.
`aria-label`	`string`	-	A label for the group (required for accessibility).

ToggleButtonGroupItem

Individual toggle buttons within a group.

Prop	Type	Default	Description
`variant`	`"default" \| "outline"`	-	Override the variant from the parent group.
`size`	`"default" \| "sm" \| "lg"`	-	Override the size from the parent group.
`isSelected`	`boolean`	-	Whether the toggle button is selected (controlled).
`defaultSelected`	`boolean`	`false`	Whether the toggle button is selected by default (uncontrolled).
`onChange`	`(isSelected: boolean) => void`	-	Handler that is called when the selection state changes.
`isDisabled`	`boolean`	`false`	Whether the toggle button is disabled.
`aria-label`	`string`	-	A label for the button (required if no visible text).

Accessibility

Each toggle button in the group should have an aria-label or visible text to identify it to assistive technology. The group itself should also have an aria-label describing the purpose of the group.

// Good: group and items have labels
<ToggleButtonGroup variant="outline" aria-label="Text formatting">
  <ToggleButtonGroupItem aria-label="Toggle bold">
    <BoldIcon />
  </ToggleButtonGroupItem>
  <ToggleButtonGroupItem aria-label="Toggle italic">
    <ItalicIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>
 
// Bad: missing labels
<ToggleButtonGroup variant="outline">
  <ToggleButtonGroupItem>
    <BoldIcon />
  </ToggleButtonGroupItem>
</ToggleButtonGroup>

Toggle Button - Individual toggle button component
Button Group - For grouping regular buttons

Toggle Button Tooltip

On This Page

Installation Usage Features Examples Default Outline Size API Reference ToggleButtonGroup ToggleButtonGroupItem Accessibility Related