# Switch Primitive

Switch 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 Switch anatomy with the Runtime wiring included.
```astro
---
import { Switch } from "@starwind-ui/astro/switch";
---

<Switch.Root>
  <Switch.Thumb />
</Switch.Root>
```

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

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

### HTML
Render the Switch data-sw-* contract yourself, then initialize createSwitch.
```html
<span data-sw-switch role="switch">
  <span data-sw-switch-thumb></span>
  <input data-sw-switch-input type="checkbox" aria-hidden="true" tabindex="-1" />
</span>

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

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

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

<template>
  <Switch.Root>
    <Switch.Thumb />
  </Switch.Root>
</template>
```
## API Reference
### Root
The main element that owns the Switch Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-switch` |
| Role | `switch` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| checked | `boolean` | - | control | Controls whether Switch is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| defaultChecked | `boolean` | false | control | Sets whether Switch starts checked for uncontrolled usage. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| id | `string` | - | option | Sets the id used by the associated native control. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| nativeButton | `boolean` | false | rendering | Renders the control as a native button element. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | false | option | Marks the form control as required. | - |
| uncheckedValue | `string` | - | option | Sets the value submitted when the checkbox is unchecked. | - |
| value | `string` | - | option | Controls the current Switch value. | - |
| onCheckedChange | `(checked: boolean, details: SwitchCheckedChangeDetails) => void` | - | callback | Runs when the Switch checked state changes. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-checked` | state | - | Reflects the checked state on the Root part. |
| `data-default-checked` | prop | - | Reflects the default checked prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-filled` | state | - | Reflects the filled state on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-id` | prop | - | Reflects the id prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-unchecked` | state | - | Reflects the unchecked state on the Root part. |
| `data-unchecked-value` | prop | - | Reflects the unchecked value prop 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 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checked | `boolean` | checked | defaultChecked | `data-default-checked` | `getChecked` | `setChecked` | Tracks whether Switch is checked. | **React:** Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.<br>**Astro:** Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.<br>**Runtime / HTML:** Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| checkedChange | onCheckedChange | starwind:checked-change | checked: `boolean` | SwitchCheckedChangeDetails | before-state-commit | Yes | Fires when the checked state changes for Switch. | 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 |
| --- | --- | --- | --- | --- |
| `setChecked` | state: checked | emit: false | Yes | Updates whether Switch is checked from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Switch is disabled from Runtime code. |
| `setFormOptions` | props: form, name, required, uncheckedValue, value | - | No | Updates Switch form-related options from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-switch`, `role`, `aria-checked`, `data-checked`, `data-unchecked`, `data-default-checked`, `data-disabled` | The visible switch needs ARIA and state styling before the controller attaches. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Thumb
The draggable thumb for Switch.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-switch-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch-thumb` | runtime | - | Marks the Thumb part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| thumb | Yes |

### Input
The native input synchronized by Switch.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-switch-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| input | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-switch-input` | The runtime needs the sibling input placeholder so it can attach form state after hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |

### Unchecked Input
The hidden native input used when Switch submits an unchecked value.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-switch-unchecked-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-switch-unchecked-input` | runtime | - | Marks the Unchecked Input part so Starwind Runtime can find it. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createSwitch`](/docs/runtime/#create-switch) |
| Import | `@starwind-ui/runtime/switch` |
| Root part | root |
| Option props | checked, defaultChecked, disabled, form, id, name, readOnly, required, uncheckedValue, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, id, name, required, uncheckedValue, value |
| Hidden input | input (checkbox) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Switch](/docs/components/switch/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/switch` | `createSwitch` |
| Astro Primitive | `@starwind-ui/astro/switch` | `Switch`, `SwitchRoot`, `SwitchThumb` |
| React Primitive | `@starwind-ui/react/switch` | `Switch`, `SwitchRoot`, `SwitchThumb` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Switch` |
| runtime-factory | `createSwitch` |
| part | `Switch.Root` |
| part | `Switch.Thumb` |
## 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.1
- 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.
- Preserved native form association when React reconciles controlled checked state.
### v0.1.0
- Introduced checked state, form participation, and checked-change events.