# Toggle Group

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";
---

<ToggleGroup multiple defaultValue={["bold", "italic"]} aria-label="Text formatting">
  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
  <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
</ToggleGroup>
```
  </div>
  <div slot="react">
```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";

export function Example() {
  return (
    <>
      <ToggleGroup multiple defaultValue={["bold", "italic"]} aria-label="Text formatting">
        <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
        <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
        <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";
</script>

<template>
  <ToggleGroup multiple :defaultValue="['bold', 'italic']" aria-label="Text formatting">
    <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
    <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
    <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
  </ToggleGroup>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add toggle-group --framework astro
```
</DocsTabsContent>
```bash
npx starwind@latest add toggle-group --framework react
```
</DocsTabsContent>
```bash
npx starwind@latest add toggle-group --framework vue
```
</DocsTabsContent>
</DocsTabs>

## Usage

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";
---

<ToggleGroup defaultValue={["left"]} variant="outline" aria-label="Alignment">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>
```
  </div>
  <div slot="react">
```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";

export function Example() {
  return (
    <>
      <ToggleGroup defaultValue={["left"]} variant="outline" aria-label="Alignment">
        <ToggleGroupItem value="left">Left</ToggleGroupItem>
        <ToggleGroupItem value="center">Center</ToggleGroupItem>
        <ToggleGroupItem value="right">Right</ToggleGroupItem>
      </ToggleGroup>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";
</script>

<template>
  <ToggleGroup :defaultValue="['left']" variant="outline" aria-label="Alignment">
    <ToggleGroupItem value="left">Left</ToggleGroupItem>
    <ToggleGroupItem value="center">Center</ToggleGroupItem>
    <ToggleGroupItem value="right">Right</ToggleGroupItem>
  </ToggleGroup>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Composition

Place each toggle item inside the group:

```text
ToggleGroup
├── ToggleGroupItem
└── ToggleGroupItem
```

## 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`.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";
---

<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>
```
</div>
<div slot="react">
```tsx
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>
    </>
  );
}
```
</div>
<div slot="vue">
```vue
<script setup lang="ts">
import { ToggleGroup, ToggleGroupItem } from "@/components/starwind/toggle-group";
</script>

<template>
  <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>
</template>
```
</div>
</FrameworkCodeSwitcher>

## Size Migration

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

## API Reference
### ToggleGroup
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `string[]` | No | - | Primitive override | Sets the initial value when the component is uncontrolled. |
| `loopFocus` | `boolean` | No | - | Primitive override | Wraps keyboard focus from the last item to the first and vice versa. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
| `spacing` | `number` | No | `2` | Wrapper prop | Sets the space between grouped controls. |
| `variant` | `"default" \| "outline"` | No | `"default"` | Wrapper prop | Selects the component's visual variant. |
- Inherits div attributes. Omits `defaultValue` and `onChange`.

### ToggleGroupItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultPressed` | `boolean` | No | - | Primitive override | Sets the initial pressed state when the control is uncontrolled. |
| `nativeButton` | `boolean` | No | - | Primitive override | Uses native button semantics for the interactive control. |
| `variant` | `"default" \| "outline"` | No | - | Wrapper prop | Selects the component's visual variant. |
- Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Toggle Primitive](/docs/primitives/toggle/)
- Primitive: [Toggle Group Primitive](/docs/primitives/toggle-group/)
- Runtime factory: [`createToggle`](/docs/runtime/#create-toggle) from `@starwind-ui/runtime/toggle`
- Runtime factory: [`createToggleGroup`](/docs/runtime/#create-toggle-group) 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](/docs/primitives/toggle/) and [Toggle Group Primitive](/docs/primitives/toggle-group/) for the underlying unstyled anatomy and behavior API.