# Toggle Group

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
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>
```
  </div>
  <div slot="react">
```tsx
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>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

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

## Installation

```bash
npx starwind@latest add toggle-group
```

## Usage

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

## Framework Availability
Toggle Group is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## 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. |
| `size` | `"sm" \| "md" \| "lg"` | No | - | Wrapper prop | Selects the component's visual size. |
| `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

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