ui/components/toggle-group

Toggle Group

Compound toggle button group with keyboard navigation for single or multiple selection.

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupDefault() {7   const [value, setValue] = useState<string | null>("all");8 9   return (10     <ToggleGroup label="File change filter" value={value} onChange={setValue}>11       <ToggleGroup.Item value="all">All</ToggleGroup.Item>12       <ToggleGroup.Item value="added">Added</ToggleGroup.Item>13       <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>14       <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>15     </ToggleGroup>16   );17 }18

Installation

$pnpm exec dgadd add ui/toggle-group

[Installs to]src/components/ui/toggle-group[Item]ui/toggle-group

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupDefault() {7   const [value, setValue] = useState<string | null>("all");8 9   return (10     <ToggleGroup label="File change filter" value={value} onChange={setValue}>11       <ToggleGroup.Item value="all">All</ToggleGroup.Item>12       <ToggleGroup.Item value="added">Added</ToggleGroup.Item>13       <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>14       <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>15     </ToggleGroup>16   );17 }18

Examples

Variants

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupVariants() {7   const [filter, setFilter] = useState<string | null>("modified");8   return (9     <div className="flex flex-col gap-6">10       <div className="flex flex-col gap-1.5">11         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">Default</span>12         <ToggleGroup13           label="File filter (default variant)"14           value={filter}15           onChange={setFilter}16           variant="default"17         >18           <ToggleGroup.Item value="all">All</ToggleGroup.Item>19           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>20           <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>21           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>22         </ToggleGroup>23       </div>24 25       <div className="flex flex-col gap-1.5">26         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">Bracket</span>27         <ToggleGroup28           label="File filter (bracket variant)"29           value={filter}30           onChange={setFilter}31           variant="bracket"32         >33           <ToggleGroup.Item value="all">All</ToggleGroup.Item>34           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>35           <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>36           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>37         </ToggleGroup>38       </div>39 40       <div className="flex flex-col gap-1.5">41         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">Pill</span>42         <ToggleGroup43           label="File filter (pill variant)"44           value={filter}45           onChange={setFilter}46           variant="pill"47         >48           <ToggleGroup.Item value="all">All</ToggleGroup.Item>49           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>50           <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>51           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>52         </ToggleGroup>53       </div>54 55       <div className="flex flex-col gap-1.5">56         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">57           Underline58         </span>59         <ToggleGroup60           label="File filter (underline variant)"61           value={filter}62           onChange={setFilter}63           variant="underline"64         >65           <ToggleGroup.Item value="all">All</ToggleGroup.Item>66           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>67           <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>68           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>69         </ToggleGroup>70       </div>71     </div>72   );73 }74

With Counts

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { createToggleGroup } from "@/components/ui/toggle-group";5 6 const SmallSeverityGroup = createToggleGroup(["error", "warning", "info"] as const);7 const MediumSeverityGroup = createToggleGroup(["error", "warning"] as const);8 9 type SmallSeverity = (typeof SmallSeverityGroup.values)[number];10 type MediumSeverity = (typeof MediumSeverityGroup.values)[number];11 12 export default function ToggleGroupCounts() {13   const [smallFilter, setSmallFilter] = useState<SmallSeverity | null>("error");14   const [mediumFilter, setMediumFilter] = useState<MediumSeverity | null>("error");15 16   return (17     <div className="flex flex-col gap-4">18       <SmallSeverityGroup19         label="Severity filter (small)"20         value={smallFilter}21         onChange={setSmallFilter}22         allowDeselect23         size="sm"24       >25         <SmallSeverityGroup.Item value="error" count={3}>26           Error27         </SmallSeverityGroup.Item>28         <SmallSeverityGroup.Item value="warning" count={12}>29           Warning30         </SmallSeverityGroup.Item>31         <SmallSeverityGroup.Item value="info" count={27}>32           Info33         </SmallSeverityGroup.Item>34       </SmallSeverityGroup>35       <MediumSeverityGroup36         label="Severity filter (medium)"37         value={mediumFilter}38         onChange={setMediumFilter}39         allowDeselect40         size="md"41       >42         <MediumSeverityGroup.Item value="error" count={3}>43           Error44         </MediumSeverityGroup.Item>45         <MediumSeverityGroup.Item value="warning" count={12}>46           Warning47         </MediumSeverityGroup.Item>48       </MediumSeverityGroup>49     </div>50   );51 }52

Multiple Selection

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupMultiple() {7   const [severity, setSeverity] = useState<readonly string[]>(["high", "critical"]);8 9   return (10     <ToggleGroup11       label="Severity levels"12       selectionMode="multiple"13       value={severity}14       onChange={setSeverity}15     >16       <ToggleGroup.Item value="low">Low</ToggleGroup.Item>17       <ToggleGroup.Item value="medium">Medium</ToggleGroup.Item>18       <ToggleGroup.Item value="high">High</ToggleGroup.Item>19       <ToggleGroup.Item value="critical">Critical</ToggleGroup.Item>20     </ToggleGroup>21   );22 }23

Sizes

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupSizes() {7   const [value, setValue] = useState<string | null>("added");8 9   return (10     <div className="flex flex-col gap-6">11       <div className="flex flex-col gap-1.5">12         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">13           Small (sm)14         </span>15         <ToggleGroup label="File filter (small)" value={value} onChange={setValue} size="sm">16           <ToggleGroup.Item value="all">All</ToggleGroup.Item>17           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>18           <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>19           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>20         </ToggleGroup>21       </div>22 23       <div className="flex flex-col gap-1.5">24         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">25           Medium (md)26         </span>27         <ToggleGroup label="File filter (medium)" value={value} onChange={setValue} size="md">28           <ToggleGroup.Item value="all">All</ToggleGroup.Item>29           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>30           <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>31           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>32         </ToggleGroup>33       </div>34     </div>35   );36 }37

Vertical

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupVertical() {7   const [value, setValue] = useState<string | null>("modified");8 9   return (10     <ToggleGroup11       label="File filter (vertical)"12       value={value}13       onChange={setValue}14       orientation="vertical"15     >16       <ToggleGroup.Item value="all">All</ToggleGroup.Item>17       <ToggleGroup.Item value="added">Added</ToggleGroup.Item>18       <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>19       <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>20     </ToggleGroup>21   );22 }23

Disabled

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupDisabled() {7   const [value, setValue] = useState<string | null>("added");8 9   return (10     <div className="flex flex-col gap-6">11       <div className="flex flex-col gap-1.5">12         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">13           Group disabled14         </span>15         <ToggleGroup16           label="File filter (group disabled)"17           value={value}18           onChange={setValue}19           disabled20         >21           <ToggleGroup.Item value="all">All</ToggleGroup.Item>22           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>23           <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>24           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>25         </ToggleGroup>26       </div>27 28       <div className="flex flex-col gap-1.5">29         <span className="text-[11px] uppercase tracking-wider text-muted-foreground">30           Per-item disabled31         </span>32         <ToggleGroup label="File filter (per-item disabled)" value={value} onChange={setValue}>33           <ToggleGroup.Item value="all">All</ToggleGroup.Item>34           <ToggleGroup.Item value="added">Added</ToggleGroup.Item>35           <ToggleGroup.Item value="modified" disabled>36             Modified37           </ToggleGroup.Item>38           <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>39         </ToggleGroup>40       </div>41     </div>42   );43 }44

API Reference

ToggleGroup

Name	Type	Default	Description
selectionMode	"single" \| "multiple"	"single"	Switches between radio-style single selection and pressed-button-style multiple selection. Switches value/onChange/defaultValue from string\|null to readonly string[].
value	string \| null \| readonly string[]	—	Controlled selected value(s). string\|null for single mode, readonly string[] for multiple.
defaultValue	string \| null \| readonly string[]	null (single) \| [] (multiple)	Initial selected value(s) for uncontrolled mode.
onChange	((value: string \| null) => void) \| ((value: readonly string[]) => void)	—	Fired when the selected value(s) change.
allowDeselect	boolean	false	Single mode only. When true, clicking the active item deselects it (allowing a null value).
disabled	boolean	false	Disables the entire group.
size	"sm" \| "md"	"sm"	Item density token. "sm" is 36px, rising to a 44px target on coarse pointers; "md" is always a 44px target.
variant	"default" \| "bracket" \| "pill" \| "underline"	"default"	Item style: default outlines, bracket adds [ ], pill fills, underline rules.
orientation	"horizontal" \| "vertical"	"horizontal"	Layout axis and arrow-key navigation direction.
wrap	boolean	true	When true, arrow navigation wraps and horizontal items flex-wrap.
highlighted	string \| null	—	Controlled highlighted (focused) value for cross-component navigation.
onHighlightChange	(value: string \| null) => void	—	Fired when the highlighted value changes.
onNavigationBoundaryReached	(direction: "previous" \| "next", event: KeyboardEvent, key: string) => void	—	Fired when arrow navigation reaches the first/last item with wrap disabled.
label	string	—	Accessible name for the group container.
aria-labelledby	string	—	ID of the element labelling the group.
name	string	—	Single mode only. Form field name; renders a hidden input for native form submission.
childrenrequired	ReactNode	—	ToggleGroup.Item children.

ToggleGroup.Item

Name	Type	Default	Description
valuerequired	string	—	Stable identifier matched against the group value.
count	number	—	Optional trailing count rendered as [label count].
disabled	boolean	false	Disables this item only; removed from arrow navigation and focus.
childrenrequired	ReactNode	—	Item label.

Data attributes

Attribute	Applies to	Values	Description
data-state	ToggleGroup.Item	"on" \| "off"	Reflects whether the item is selected.
data-highlighted	ToggleGroup.Item	present when highlighted	Marks the roving-focus item.
data-value	ToggleGroup.Item	item value	Exposes the item value used for selection and indicator positioning.
data-variant	ToggleGroup	"default" \| "pill" \| "underline" \| "bracket"	Reflects the visual variant on the group root.
data-orientation	ToggleGroup	"horizontal" \| "vertical"	Reflects the layout and arrow-key axis.

Accessibility

Keyboard Navigation

Arrow keys move focus between toggle items with wrapping. Single mode follows focus; multiple mode and allow-deselect single mode use button semantics and toggle with Enter or Space.

Key	Action
ArrowRight / ArrowDown	Moves focus to the next enabled item; wraps when wrap is true.
ArrowLeft / ArrowUp	Moves focus to the previous enabled item; wraps when wrap is true.
Home / End	Moves focus to the first or last enabled item.
Enter / Space	Toggles the focused item in multiple mode or allow-deselect single mode; native radio-style single mode changes selection during arrow navigation.

With keyboard navigation

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { ToggleGroup } from "@/components/ui/toggle-group";5 6 export default function ToggleGroupDefault() {7   const [value, setValue] = useState<string | null>("all");8 9   return (10     <ToggleGroup label="File change filter" value={value} onChange={setValue}>11       <ToggleGroup.Item value="all">All</ToggleGroup.Item>12       <ToggleGroup.Item value="added">Added</ToggleGroup.Item>13       <ToggleGroup.Item value="modified">Modified</ToggleGroup.Item>14       <ToggleGroup.Item value="deleted">Deleted</ToggleGroup.Item>15     </ToggleGroup>16   );17 }18

Notes

Requires @diffgazer/keys (package mode)

ToggleGroup's arrow-key navigation imports from the required @diffgazer/keys peer. Package consumers must install @diffgazer/keys with @diffgazer/ui; install both from npm (npm install @diffgazer/ui @diffgazer/keys), or take the component from the live registry instead (npx shadcn add https://r.b4r7.dev/r/ui/toggle-group.json). Importing @diffgazer/ui/components/toggle-group without keys fails at module load with an error naming the missing @diffgazer/keys package. Copy/dgadd consumers do not need the package — copy mode rewrites the keyboard hooks to local source.

Compound Component

ToggleGroup uses compound sub-components (ToggleGroup.Item) rather than a data array. Each item accepts children for the label and an optional count prop that renders as [label count].

Composition Contract

Use ToggleGroup.Item as an explicit child in the ToggleGroup JSX tree. Custom item UI belongs inside ToggleGroup.Item. Components that create items internally from an opaque wrapper are not part of the current public contract.

Keyboard Navigation

Arrow keys move roving focus with wrapping by default. In single mode, selection follows focus unless allowDeselect is enabled; in multiple mode, arrow keys move focus and Enter/Space toggles the focused item. Highlight state can be controlled externally via highlighted and onHighlightChange props. Use onNavigationBoundaryReached for composite focus handoff when wrap is false.

Role semantics

Single mode without allowDeselect renders as radiogroup/radio with aria-checked and allows at most one active choice. Initial selection is optional: defaultValue=null starts with no radio checked. Multiple mode and allow-deselect single mode render as group plus button-style items with aria-pressed because each item is independently toggleable.

Source

Install via CLI: pnpm exec dgadd add ui/toggle-group. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Toggle Group

Installation

Usage

Examples

Variants

With Counts

Multiple Selection

Sizes

Vertical

Disabled

API Reference

ToggleGroup

ToggleGroup.Item

Data attributes

Accessibility

Keyboard Navigation

With keyboard navigation

Notes

Requires @diffgazer/keys (package mode)

Compound Component

Composition Contract

Keyboard Navigation

Role semantics

Source

View component source (28 files)