Toggle Group

Installation

pnpm dlx shadcn@latest add https://prototyper-ui.com/r/toggle-group.json

npx shadcn@latest add https://prototyper-ui.com/r/toggle-group.json

yarn dlx shadcn@latest add https://prototyper-ui.com/r/toggle-group.json

bunx --bun shadcn@latest add https://prototyper-ui.com/r/toggle-group.json

This will add the following files to your project:

components/ui/toggle-group.tsx

Usage

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

<ToggleGroup defaultValue={["center"]} aria-label="Text alignment">
  <ToggleGroupItem value="left" aria-label="Align left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">Right</ToggleGroupItem>
</ToggleGroup>

Anatomy

<ToggleGroup>
  <ToggleGroupItem />
  <ToggleGroupItem />
  <ToggleGroupItem />
</ToggleGroup>

Sub-component	`data-slot`	Purpose	Required
`ToggleGroup`	`toggle-group`	Root container, manages selection state	Yes
`ToggleGroupItem`	`toggle-group-item`	Individual toggle button within the group	Yes

Examples

Outline

Multiple

Vertical

Small

Large

Disabled

Styling

Data Slots

Use data-slot attributes to target specific parts of the toggle group:

Slot name	Element
`toggle-group`	Root container for all toggle items
`toggle-group-item`	Individual toggle button

Customization Examples

/* Style all pressed items in a toggle group */
[data-slot="toggle-group-item"][data-state="on"] {
  @apply bg-primary text-primary-foreground;
}

/* Add spacing between items */
[data-slot="toggle-group"] {
  @apply gap-1;
}

{/* Override styles via className */}
<ToggleGroup className="rounded-lg border bg-background p-1">
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
</ToggleGroup>

API Reference

ToggleGroup

Root container that manages which toggle items are pressed.

Prop

Type

All Base UI ToggleGroup props are forwarded via ...props.

ToggleGroupItem

An individual toggle button within the group.

Prop

Type

All Base UI Toggle props are forwarded via ...props.

Accessibility

Keyboard Interactions

Key	Action
`Space`	Toggles the pressed state of the focused item
`Enter`	Toggles the pressed state of the focused item
`Tab`	Moves focus into / out of the toggle group
`ArrowRight`	Moves focus to the next item (horizontal orientation)
`ArrowLeft`	Moves focus to the previous item (horizontal orientation)
`ArrowDown`	Moves focus to the next item (vertical orientation)
`ArrowUp`	Moves focus to the previous item (vertical orientation)
`Home`	Moves focus to the first item
`End`	Moves focus to the last item

ARIA Attributes

ToggleGroup renders as a group with aria-label describing the group purpose.
Each ToggleGroupItem renders as a <button> with aria-pressed attribute.
aria-pressed="true" when the item is in the pressed state, aria-pressed="false" when unpressed.
aria-disabled is set when the group or an individual item is disabled.
aria-orientation is set to match the orientation prop.
Focus management follows the roving tabindex pattern so only one item is tabbable at a time.

Related Components

Toggledependency

A two-state toggle button built on Base UI.

Related Components

On this page