# Toggle Primitive

Toggle is a Starwind Runtime primitive in the single-boolean-control contract family.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| pressed | `boolean` | - | control | Controls the pressed state for Toggle. |
| defaultPressed | `boolean` | false | control | Controls the default pressed state for Toggle. |
| 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: unknown, details: TogglePressedChangeDetails) => void` | - | callback | Runs when on pressed change changes for Toggle. |
#### 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 supports controlled and default state with pressed and defaultPressed props. Runtime/HTML reads initial state from data-default-pressed, emits starwind:pressed-change, and updates with setPressed. 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 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| pressedChange | onPressedChange | starwind:pressed-change | pressed | TogglePressedChangeDetails | - | - | Fires when the pressed state changes for Toggle. |
#### 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 |
#### 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` |