Toggle Button Group

A toggle button group allows users to select one or more options from a set.

<ToggleButtonGroup aria-label="Text formatting">
  <ToggleButton id="bold" isIconOnly aria-label="Bold">
    <BoldIcon />
  </ToggleButton>
  <ToggleButton id="italic" isIconOnly aria-label="Italic">
    <ItalicIcon />
  </ToggleButton>
  <ToggleButton id="underline" isIconOnly aria-label="Underline">
    <UnderlineIcon />
  </ToggleButton>
</ToggleButtonGroup>

Installation

npm

pnpm

yarn

bun

npx shadcn@latest add @dotui/toggle-button-group

Usage

Use toggle button groups to let users toggle between multiple options.

import { ToggleButton } from '@/components/ui/toggle-button'
import { ToggleButtonGroup } from '@/components/ui/toggle-button-group'

<ToggleButtonGroup aria-label="Text alignment" defaultSelectedKeys={['left']}>
  <ToggleButton id="left">Left</ToggleButton>
  <ToggleButton id="center">Center</ToggleButton>
  <ToggleButton id="right">Right</ToggleButton>
</ToggleButtonGroup>

Selection

Each ToggleButton needs an id; selection keys map to those ids. Selection is single by default — set selectionMode="multiple" to allow several. Use defaultSelectedKeys for uncontrolled state, or selectedKeys with onSelectionChange to control it, and pass disallowEmptySelection to keep at least one selected.

const [selected, setSelected] = React.useState(new Set(['bold']))

<ToggleButtonGroup
  selectionMode="multiple"
  selectedKeys={selected}
  onSelectionChange={setSelected}
  aria-label="Text formatting"
>
  <ToggleButton id="bold">Bold</ToggleButton>
  <ToggleButton id="italic">Italic</ToggleButton>
  <ToggleButton id="underline">Underline</ToggleButton>
</ToggleButtonGroup>

Examples

Icon Buttons

Text Alignment

View Mode

API Reference

A toggle button group allows a user to toggle multiple options, with single or multiple selection.

Prop	Type	Default
	`"default" \| "primary" \| "quiet"`	`'default'`
	`union`	`'md'`
	`boolean`	`—`
	`ReactNode \| function`	`—`
	`boolean`	`—`
	`Orientation`	`'horizontal'`

	`"multiple" \| "single"`	`'single'`
	`Iterable<Key>`	`—`
	`Iterable<Key>`	`—`
	`function`	`—`
	`boolean`	`—`

Last updated on 7/9/2026