# Toggle Primitive

Toggle is a Starwind Runtime primitive in the single-boolean-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Toggle anatomy with the Runtime wiring included.
```astro
---
import { Toggle } from "@starwind-ui/astro/toggle";
---

<Toggle.Root>Toggle</Toggle.Root>
```

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

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

### HTML
Render the Toggle data-sw-* contract yourself, then initialize createToggle.
```html
<button data-sw-toggle>Toggle</button>

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

  const root = document.querySelector("[data-sw-toggle]");
  if (root) {
    createToggle(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Toggle anatomy.
```vue
<script setup lang="ts">
import Toggle from "@starwind-ui/vue/toggle";
</script>

<template>
  <Toggle.Root>Toggle</Toggle.Root>
</template>
```
## API Reference
### Root
The main element that owns the Toggle Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-toggle` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| pressed | `boolean` | - | control | Controls the pressed state for Toggle. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
| defaultPressed | `boolean` | false | control | Controls the default pressed state for Toggle. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| nativeButton | `boolean` | true | rendering | Renders the control as a native button element. | - |
| syncGroup | `string` | - | option | Configures the sync group option for the Root part. | - |
| value | `string` | - | option | Controls the current Toggle value. | - |
| onPressedChange | `(pressed: boolean, details: TogglePressedChangeDetails) => void` | - | callback | Runs when on pressed change changes for Toggle. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toggle` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-pressed` | prop | - | Reflects the default pressed prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-native` | prop | - | Reflects the native prop on the Root part. |
| `data-pressed` | state | - | Reflects the pressed state on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-sync-group` | prop | - | Reflects the sync group prop on the Root part. |
| `data-unpressed` | state | - | Reflects the unpressed state on the Root part. |
| `data-value` | prop | - | Reflects the value prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| pressed | `boolean` | pressed | defaultPressed | `data-default-pressed` | `getPressed` | `setPressed` | Tracks whether Toggle is pressed. | **React:** Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.<br>**Astro:** Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.<br>**Runtime / HTML:** Use data-default-pressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| pressedChange | onPressedChange | starwind:pressed-change | pressed: `boolean` | TogglePressedChangeDetails | before-state-commit | Yes | Fires when the pressed state changes for Toggle. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setPressed` | state: pressed | emit: false, sync: true | Yes | Updates whether Toggle is pressed from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Toggle is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Context
| Name | Direction | Values |
| --- | --- | --- |
| toggle-group | consumes | disabled, value |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-toggle`, `aria-pressed`, `data-default-pressed`, `data-state`, `data-value` | Toggle state styling and ARIA button state must be correct before hydration. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createToggle`](/docs/runtime/#create-toggle) |
| Import | `@starwind-ui/runtime/toggle` |
| Root part | root |
| Option props | defaultPressed, disabled, nativeButton, pressed, syncGroup, value |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Toggle](/docs/components/toggle/) | Direct Primitive |
| [Toggle Group](/docs/components/toggle-group/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/toggle` | `createToggle` |
| Astro Primitive | `@starwind-ui/astro/toggle` | `Toggle`, `ToggleRoot` |
| React Primitive | `@starwind-ui/react/toggle` | `Toggle`, `ToggleRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Toggle` |
| runtime-factory | `createToggle` |
| part | `Toggle.Root` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.1
- Prevented generic Toggle initialization from claiming roots owned by the Runtime Theme Toggle.
### v0.1.0
- Introduced pressed state, disabled behavior, and pressed-change events.