Group toggles that belong together. Use type="single" for one value or type="multiple" when several can remain on.
tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"export function Example() { return ( <ToggleGroup type="multiple"> <ToggleGroupItem value="bold" aria-label="Toggle bold"> <BoldIcon /> </ToggleGroupItem> <ToggleGroupItem value="italic" aria-label="Toggle italic"> <ItalicIcon /> </ToggleGroupItem> <ToggleGroupItem value="underline" aria-label="Toggle underline"> <UnderlineIcon /> </ToggleGroupItem> </ToggleGroup> )}Installation
npx @arctis-sh/@arctis-sh/ui@latest add toggle-groupUsage
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"<ToggleGroup type="single"> <ToggleGroupItem value="a">A</ToggleGroupItem> <ToggleGroupItem value="b">B</ToggleGroupItem> <ToggleGroupItem value="c">C</ToggleGroupItem></ToggleGroup>Composition
ToggleGroup ├── ToggleGroupItem └── ToggleGroupItem
Outline
Set variant="outline" on the group to give every item a border.
tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"export function Example() { return ( <ToggleGroup type="single" variant="outline" defaultValue="all"> <ToggleGroupItem value="all">All</ToggleGroupItem> <ToggleGroupItem value="missed">Missed</ToggleGroupItem> </ToggleGroup> )}Size
Set size on the group to sm, default, or lg; its items follow automatically.
tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"export function Example() { return ( <div className="flex flex-col items-center gap-4"> <ToggleGroup type="single" size="sm" defaultValue="left"> <ToggleGroupItem value="top" aria-label="Align top"> <AlignTopIcon /> </ToggleGroupItem> <ToggleGroupItem value="bottom" aria-label="Align bottom"> <AlignBottomIcon /> </ToggleGroupItem> <ToggleGroupItem value="left" aria-label="Align left"> <AlignLeftIcon /> </ToggleGroupItem> <ToggleGroupItem value="right" aria-label="Align right"> <AlignRightIcon /> </ToggleGroupItem> </ToggleGroup> <ToggleGroup type="single" defaultValue="left"> <ToggleGroupItem value="top" aria-label="Align top"> <AlignTopIcon /> </ToggleGroupItem> <ToggleGroupItem value="bottom" aria-label="Align bottom"> <AlignBottomIcon /> </ToggleGroupItem> <ToggleGroupItem value="left" aria-label="Align left"> <AlignLeftIcon /> </ToggleGroupItem> <ToggleGroupItem value="right" aria-label="Align right"> <AlignRightIcon /> </ToggleGroupItem> </ToggleGroup> </div> )}Spacing
Items start with a 2 gap. Pass spacing={0} to join them into one control; outline joins use the same edge treatment as Button Group.
tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"export function Example() { return ( <ToggleGroup type="single" variant="outline" spacing={0} defaultValue="left" > <ToggleGroupItem value="top" aria-label="Align top"> <AlignTopIcon /> </ToggleGroupItem> <ToggleGroupItem value="bottom" aria-label="Align bottom"> <AlignBottomIcon /> </ToggleGroupItem> <ToggleGroupItem value="left" aria-label="Align left"> <AlignLeftIcon /> </ToggleGroupItem> <ToggleGroupItem value="right" aria-label="Align right"> <AlignRightIcon /> </ToggleGroupItem> </ToggleGroup> )}Vertical
Stack the row with orientation="vertical".
tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"export function Example() { return ( <ToggleGroup type="multiple" orientation="vertical"> <ToggleGroupItem value="bold" aria-label="Toggle bold"> <BoldIcon /> </ToggleGroupItem> <ToggleGroupItem value="italic" aria-label="Toggle italic"> <ItalicIcon /> </ToggleGroupItem> <ToggleGroupItem value="underline" aria-label="Toggle underline"> <UnderlineIcon /> </ToggleGroupItem> </ToggleGroup> )}Disabled
disabled on the group locks all items at once.
tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"export function Example() { return ( <ToggleGroup type="multiple" disabled> <ToggleGroupItem value="bold" aria-label="Toggle bold"> <BoldIcon /> </ToggleGroupItem> <ToggleGroupItem value="italic" aria-label="Toggle italic"> <ItalicIcon /> </ToggleGroupItem> <ToggleGroupItem value="underline" aria-label="Toggle underline"> <UnderlineIcon /> </ToggleGroupItem> </ToggleGroup> )}Custom
Style individual items for labels, weights, or other one-off treatments. Joined outlines still follow spacing={0}.
tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"export function Example() { return ( <ToggleGroup type="single" variant="outline" spacing={0} defaultValue="normal" className="flex-wrap" > <ToggleGroupItem value="light" className="px-3 font-light"> Aa Light </ToggleGroupItem> <ToggleGroupItem value="normal" className="px-3 font-normal"> Aa Normal </ToggleGroupItem> <ToggleGroupItem value="medium" className="px-3 font-medium"> Aa Medium </ToggleGroupItem> <ToggleGroupItem value="bold" className="px-3 font-bold"> Aa Bold </ToggleGroupItem> </ToggleGroup> )}API Reference
ToggleGroup
| Prop | Type | Default |
|---|---|---|
| type | "single" | "multiple" | "single" |
| value | string | string[] | — |
| defaultValue | string | string[] | — |
| onValueChange | (value: string | string[]) => void | — |
| variant | "default" | "outline" | "default" |
| size | "default" | "sm" | "lg" | "default" |
| spacing | number | 2 |
| orientation | "horizontal" | "vertical" | "horizontal" |
| disabled | boolean | false |
| className | string | — |
value / defaultValue / onValueChange use a string when type="single", and a string array when type="multiple".
<ToggleGroup type="single" defaultValue="center"> <ToggleGroupItem value="left">Left</ToggleGroupItem> <ToggleGroupItem value="center">Center</ToggleGroupItem></ToggleGroup>ToggleGroupItem
| Prop | Type | Default |
|---|---|---|
| value | string | — |
| variant | "default" | "outline" | — |
| size | "default" | "sm" | "lg" | — |
| disabled | boolean | false |
| className | string | — |
Omit variant or size on an item to inherit from the group.
<ToggleGroupItem value="left">Left</ToggleGroupItem>