On this page

Toggle Group

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

<ToggleGroup defaultValue={["bold"]} aria-label="Text formatting">
  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
  <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
</ToggleGroup>

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

export function Example() {
  return (
    <>
      <ToggleGroup defaultValue={["bold"]} aria-label="Text formatting">
        <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
        <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
        <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}

Installation

pnpx starwind@latest add toggle-group

npx starwind@latest add toggle-group

yarn dlx starwind@latest add toggle-group

Usage

<ToggleGroup multiple defaultValue={["left", "center"]} variant="outline">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

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

export function Example() {
  return (
    <>
      <ToggleGroup multiple defaultValue={["left", "center"]} variant="outline">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center">Center</ToggleGroupItem>
        <ToggleGroupItem value="right">Right</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}

Sizes

ToggleGroup is the sole size owner. Set size="sm", size="md" (the default), or size="lg" on the root; items still support independent variant overrides but no longer accept size.

<ToggleGroup size="sm" defaultValue={["left"]} aria-label="Small alignment">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
</ToggleGroup>

<ToggleGroup size="lg" defaultValue={["left"]} aria-label="Large alignment">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center" variant="outline">Center</ToggleGroupItem>
</ToggleGroup>

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

export function Example() {
  return (
    <>
      <ToggleGroup size="sm" defaultValue={["left"]} aria-label="Small alignment">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center">Center</ToggleGroupItem>
      </ToggleGroup>

      <ToggleGroup size="lg" defaultValue={["left"]} aria-label="Large alignment">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center" variant="outline">Center</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}

Size migration

Before	After
`<ToggleGroup><ToggleGroupItem size="sm" /></ToggleGroup>`	`<ToggleGroup size="sm"><ToggleGroupItem /></ToggleGroup>`

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Toggle Group

Inherits div attributes. Omits `defaultValue` and `onChange`.

Contains the following additional props:

Prop Type Default

defaultValue string[] —

Description: Sets the initial value when the component is uncontrolled.
Classification: Primitive override
Primitive prop: toggle-group.Root.defaultValue

loopFocus boolean —

Description: Wraps keyboard focus from the last item to the first and vice versa.
Classification: Primitive override
Primitive prop: toggle-group.Root.loopFocus

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Wrapper prop

spacing number 2

Description: Sets the space between grouped controls.
Classification: Wrapper prop

variant "default" | "outline" "default"

Description: Selects the component's visual variant.
Classification: Wrapper prop

Toggle Group Item

Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.

Contains the following additional props:

Prop Type Default

defaultPressed boolean —

Description: Sets the initial pressed state when the control is uncontrolled.
Classification: Primitive override
Primitive prop: toggle.Root.defaultPressed

nativeButton boolean —

Description: Uses native button semantics for the interactive control.
Classification: Primitive override
Primitive prop: toggle.Root.nativeButton

variant "default" | "outline" —

Description: Selects the component's visual variant.
Classification: Wrapper prop

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Toggle Group.

Primitive API

Runtime API

Toggle primitive: createToggle from @starwind-ui/runtime/toggle
Toggle Group primitive: createToggleGroup from @starwind-ui/runtime/toggle-group

Changelog

v2.0.1

Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v2.0.0

Removed ToggleGroupItem.size; ToggleGroup now exclusively owns the shared item size.
Migration: move every item-level size value to its containing ToggleGroup. Per-item variant overrides continue to work.

v1.0.0

Added Toggle Group as a Runtime-backed component with grouped toggle state.
See the Toggle Primitive and Toggle Group Primitive for the underlying unstyled anatomy and behavior API.