Toggle Group

A set of two-state buttons that can be toggled on or off. Built on Base UI's toggle group primitive.

Last updated August 7, 2026

CreditsModifiedPublished

Segmented items merge corners on the reading-start/end (logical rounding + border-inline-start) instead of always the physical left/right

Overview

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"
 
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@/components/ui/toggle-group"
 
export function ToggleGroupDemoExample() {
  return (
    <ToggleGroup>
      <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 shadcn@latest add https://ui.persian-labs.ir/r/toggle-group.json

Usage

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
 
export function Example() {
  return (
    <ToggleGroup>
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        B
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        I
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Outline

Set spacing={0} to merge items into one segmented control.

import { AlignCenterIcon, AlignLeftIcon, AlignRightIcon } from "lucide-react"
 
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@/components/ui/toggle-group"
 
export function ToggleGroupOutlineExample() {
  return (
    <ToggleGroup variant="outline" spacing={0} defaultValue={["left"]}>
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeftIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenterIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRightIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

RTL

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"
 
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@/components/ui/toggle-group"
 
export function ToggleGroupRtlExample() {
  return (
    <ToggleGroup>
      <ToggleGroupItem value="bold" aria-label="ضخیم">
        <BoldIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="مورب">
        <ItalicIcon />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="زیرخط‌دار">
        <UnderlineIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

API Reference

ToggleGroup

Prop	Type	Default	Description
value	string[]	undefined	The pressed values. Use when controlled.
defaultValue	string[]	[]	The initially pressed values when uncontrolled.
onValueChange	(value, details) => void	—	Called when the pressed values change.
multiple	boolean	false	Whether multiple items can be pressed at once.
variant	"default" \| "outline"	"default"	Applied to every item unless overridden individually.
size	"default" \| "sm" \| "lg"	"default"	Applied to every item unless overridden individually.
spacing	number	0	Gap between items. 0 merges items into one segmented control.

ToggleGroupItem

Prop	Type	Default	Description
value	string	required	The value associated with this item.
disabled	boolean	false	Prevents interaction with this item.

Edit this page on GitHub

PreviousToggle