# ToggleGroup Primitive

ToggleGroup is a Starwind Runtime primitive in the controlled-value-group contract family.
## Anatomy
### Astro
Use the Astro primitive adapter to render ToggleGroup anatomy with the Runtime wiring included.
```astro
---
import { ToggleGroup } from "@starwind-ui/astro/toggle-group";
---

<ToggleGroup.Root />
```

### React
Use the React primitive adapter when ToggleGroup state participates in React rendering.
```tsx
import { ToggleGroup } from "@starwind-ui/react/toggle-group";

export function Example() {
  return (
    <ToggleGroup.Root />
  );
}
```

### HTML
Render the ToggleGroup data-sw-* contract yourself, then initialize createToggleGroup.
```html
<div data-sw-toggle-group role="group"></div>

<script type="module">
  import { createToggleGroup } from "@starwind-ui/runtime/toggle-group";

  const root = document.querySelector("[data-sw-toggle-group]");
  if (root) {
    createToggleGroup(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the ToggleGroup Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toggle-group` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| value | `ToggleGroupValue` | - | control | Controls the current ToggleGroup value. |
| defaultValue | `ToggleGroupValue` | - | control | Sets the initial ToggleGroup value for uncontrolled usage. |
| disabled | `boolean` | false | option | Disables the Root part. |
| loopFocus | `boolean` | true | option | Lets keyboard focus wrap around the ToggleGroup items. |
| multiple | `boolean` | false | option | Allows multiple ToggleGroup values to be selected. |
| orientation | `"horizontal" \| "vertical"` | "horizontal" | option | Sets the ToggleGroup orientation. |
| onValueChange | `(value: ToggleGroupValue, details: ToggleGroupValueChangeDetails) => void` | - | callback | Runs when the ToggleGroup value changes. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toggle-group` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-loop-focus` | prop | - | Reflects the loop focus prop on the Root part. |
| `data-multiple` | prop | - | Reflects the multiple prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ToggleGroupValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current ToggleGroup value. | React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-default-value, emits starwind:value-change, and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `ToggleGroupValue` | ToggleGroupValueChangeDetails | - | - | Fires when the value changes for ToggleGroup. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current ToggleGroup value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether ToggleGroup is disabled from Runtime code. |
| `setLoopFocus` | prop: loopFocus | - | No | Updates ToggleGroup keyboard focus wrapping from Runtime code. |
| `setMultiple` | prop: multiple | - | No | Updates whether ToggleGroup allows multiple values from Runtime code. |
| `setOrientation` | prop: orientation | - | No | Updates the ToggleGroup orientation from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| toggle-group | provides | disabled, loopFocus, multiple, orientation, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-toggle-group`, `role`, `data-default-value`, `data-disabled`, `data-loop-focus`, `data-multiple`, `data-orientation`, `data-value` | The value group needs initial selection, orientation, and group state for styling before hydration. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createToggleGroup`](/docs/runtime/#create-toggle-group) |
| Import | `@starwind-ui/runtime/toggle-group` |
| Root part | root |
| Option props | defaultValue, disabled, loopFocus, multiple, orientation, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Toggle Group](/docs/components/toggle-group/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/toggle-group` | `createToggleGroup` |
| Astro Primitive | `@starwind-ui/astro/toggle-group` | `ToggleGroup`, `ToggleGroupRoot` |
| React Primitive | `@starwind-ui/react/toggle-group` | `ToggleGroup`, `ToggleGroupRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ToggleGroup` |
| runtime-factory | `createToggleGroup` |
| part | `ToggleGroup.Root` |