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>
    </>
  );
}

Runtime example adjustment

Toggle Group owns selection and keyboard focus. defaultValue is always an array; enable multiple when more than one value may remain pressed.

Installation

pnpx starwind@latest add toggle-group

npx starwind@latest add toggle-group

yarn dlx starwind@latest add toggle-group

Framework Availability

Astro Available React Available

Toggle Group is available for Astro and React.

Usage

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

API Reference

Styled Component API

These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. 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

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

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

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

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.