Toggle Group

Forms

Actions

A set of two-state buttons that can be toggled on or off. Perfect for toolbars and option groups.

Preview

Single selection toggle group for alignment

Variants

Toggle Group comes in two visual variants

Default

Outline

Single Selection

Only one item can be active at a time

Selected: left

Multiple Selection

Multiple items can be active simultaneously

Selected: bold

Sizes

Three size options: small, medium, and large

Small

Medium (default)

Large

Props

ToggleGroup component API reference

Prop	Type	Default	Description
`type`	`'single' \| 'multiple'`	—	Selection mode (required)
`variant`	`'default' \| 'outline'`	`'default'`	Visual variant
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Toggle size
`value`	`string \| string[]`	—	Controlled value
`defaultValue`	`string \| string[]`	—	Default value (uncontrolled)
`onValueChange`	`(value: string \| string[]) => void`	—	Callback when value changes
`disabled`	`boolean`	`false`	Disable all toggles

ToggleGroupItem Props

Prop	Type	Default	Description
`value`	`string`	—	Unique value for this item (required)
`disabled`	`boolean`	`false`	Disable this toggle item

Usage

Import and implementation example

import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'
import { Bold, Italic, Underline } from 'lucide-react'

export default function Example() {
  const [value, setValue] = useState('bold')
  const [multiValue, setMultiValue] = useState(['bold'])

  return (
    <>
      {/* Single selection */}
      <ToggleGroup type="single" defaultValue="left">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center">Center</ToggleGroupItem>
        <ToggleGroupItem value="right">Right</ToggleGroupItem>
      </ToggleGroup>

      {/* Multiple selection */}
      <ToggleGroup type="multiple" defaultValue={['bold']}>
        <ToggleGroupItem value="bold">
          <Bold className="h-4 w-4" />
        </ToggleGroupItem>
        <ToggleGroupItem value="italic">
          <Italic className="h-4 w-4" />
        </ToggleGroupItem>
      </ToggleGroup>

      {/* Controlled state */}
      <ToggleGroup
        type="single"
        value={value}
        onValueChange={setValue}
      >
        <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
        <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
      </ToggleGroup>

      {/* Variants */}
      <ToggleGroup type="single" variant="default">...</ToggleGroup>
      <ToggleGroup type="single" variant="outline">...</ToggleGroup>

      {/* Sizes */}
      <ToggleGroup type="single" size="sm">...</ToggleGroup>
      <ToggleGroup type="single" size="md">...</ToggleGroup>
      <ToggleGroup type="single" size="lg">...</ToggleGroup>
    </>
  )
}

Features

Built-in functionality

Single & multiple selection: Choose one or multiple items
Two variants: Default and outline styles
Three sizes: Small, medium, and large
Controlled & uncontrolled: Flexible state management
Icon + text support: Combine icons with labels
Radix UI primitives: Built on accessible components
Keyboard navigation: Full keyboard support
Dark mode: Full dark mode support

Accessibility

Accessibility considerations

ARIA Attributes

Uses role="group" for the containerEach toggle uses aria-pressedProper focus management via Radix

Keyboard Navigation

Key	Action
`Tab`	Focus the toggle group
`Arrow Keys`	Navigate between toggles
`Space`	Toggle selected item
`Enter`	Toggle selected item

Notes

Group items are roving focus managed
Visual indication of selected state
Consider adding aria-label to icon-only groups
Disabled items are skipped in navigation

Related Components

Toggle Radio Group Button Group