Introduction

A set of toggle buttons for single- or multiple-selection, exclusive or inclusive — e.g. text-formatting controls (bold/italic/underline) or a view-switcher.

Hydration

Tier 2 — smart auto-detect. A ToggleGroup renders as static HTML and ships no client JS unless a behavioral signal is present. Pass interactive={true} to force hydration, or interactive={false} to force a static render.

It hydrates as an island when any of the following signals is present (or interactive={true} is set):

• value (controlled selection)
• defaultValue (uncontrolled initial selection)
• onValueChange

interactive prop	Result
omitted, no signal	Static — no client JS
omitted, a signal present	Hydrates as an island
true	Hydrates as an island
false	Static — no client JS

Usage

import { ToggleGroup } from "../components/ui";

export default function MyPage() {
  return (
    <ToggleGroup
      multiple
      defaultValue={["bold"]}
      items={[
        { label: "B", value: "bold" },
        { label: "I", value: "italic" },
        { label: "U", value: "underline" },
      ]}
    />
  );
}

Custom Composition

Pass children instead of items for full control over each button's content:

import { ToggleGroup } from "../components/ui";

export default function MyPage() {
  return (
    <ToggleGroup defaultValue={["list"]}>
      <ToggleGroup.Item value="grid">Grid</ToggleGroup.Item>
      <ToggleGroup.Item value="list">List</ToggleGroup.Item>
    </ToggleGroup>
  );
}

Props

Root

Prop	Type	Description
value	string[]	The currently pressed values (controlled).
defaultValue	string[]	The initially pressed values (uncontrolled).
onValueChange	(value: string[]) => void	Called when the selection changes.
multiple	boolean	Allow more than one item pressed at once. Default false (single, toggleable-off selection).
disabled	boolean	Disables every item.
orientation	"horizontal" | "vertical"	Layout flow, and the axis Arrow keys roam. Default "horizontal".
id	string	The root element's id.
variant	"outline" | "ghost"	Visual style. Default "outline".
size	"sm" | "md" | "lg"	Visual size. Default "md".
interactive	boolean	Overrides the hydration decision (see above).
class	string	Custom CSS classes for the root element.

Default composition

Prop	Type	Description
items	ToggleGroupItem[]	Buttons to render when children is omitted.

ToggleGroupItem

Prop	Type	Description
value	string	The item's unique value.
label	string | JSX.Element	The button's display content.
disabled	boolean	Disables this button.

Sub-components

Part	Description
ToggleGroup.Item	One toggle button. Requires a value prop; renders role="checkbox" in multiple mode or role="radio" otherwise.

Accessibility

• The root has role="group".
• Items render role="checkbox" + aria-pressed when multiple, or role="radio" + aria-checked otherwise.
• Arrow keys (Right/Down to move forward, Left/Up to move back) roam focus between enabled items; Home/End jump to the first/last enabled item — matching orientation.
• data-state (on/off) and data-disabled are mirrored onto each item for styling.