On this page

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

Use the Astro primitive adapter to render Switch anatomy with the Runtime wiring included.

---
import { Switch } from "@starwind-ui/astro/switch";
---

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

Use the React primitive adapter when Switch state participates in React rendering.

import { Switch } from "@starwind-ui/react/switch";

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

Render the Switch data-sw-* contract yourself, then initialize createSwitch.

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

API Reference

Root

The main element that owns the Switch Runtime instance.

Default element: span
Discovery hook: data-sw-switch
Role: switch

Props

Prop Type Default

checked boolean -

Description

Controls whether Switch is checked.

Kind

control

Targets

Full type

boolean

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

data-default-checked
starwind:checked-change
setChecked

defaultChecked boolean false

Description

Sets whether Switch starts checked for uncontrolled usage.

Kind

control

Targets

Full type

boolean

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

data-default-checked
starwind:checked-change
setChecked

disabled boolean false

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

form string -

Description: Associates the control with a form element.
Kind: option
Targets: -
Full type: string

id string -

Description: Sets the id used by the associated native control.
Kind: option
Targets: -
Full type: string

name string -

Description: Sets the submitted form field name.
Kind: option
Targets: -
Full type: string

nativeButton boolean false

Description: Renders the control as a native button element.
Kind: rendering
Targets: root
Full type: boolean

readOnly boolean false

Description: Marks the control as read-only.
Kind: option
Targets: -
Full type: boolean

required boolean false

Description: Marks the form control as required.
Kind: option
Targets: -
Full type: boolean

uncheckedValue string -

Description: Sets the value submitted when the checkbox is unchecked.
Kind: option
Targets: -
Full type: string

value string -

Description: Controls the current Switch value.
Kind: option
Targets: -
Full type: string

onCheckedChange (checked: boolean, details: SwitchCheckedChangeDetails) => void -

Description

Runs when the Switch checked state changes.

Kind

callback

Targets

Full type

(checked: boolean, details: SwitchCheckedChangeDetails) => void

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

data-default-checked
starwind:checked-change
setChecked

Events

Event Callback Value

checkedChange onCheckedChange checked: boolean

Description

Fires when the checked state changes for Switch.

DOM event

starwind:checked-change

Details type

SwitchCheckedChangeDetails

Timing

before-state-commit

Cancelable

Yes

Cancellation sequence

Check internal eligibility and intent.
Create one details object for the proposal.
Call the Runtime callback with the details object when the controller exposes one.
Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
Read details.isCanceled, including cancellation caused by preventDefault().
Apply the accepted state.
Notify Runtime subscribers and other accepted-only observers.

State

State Type Props

checked boolean checked / defaultChecked

Description

Tracks whether Switch is checked.

Initial attribute

data-default-checked

Runtime getter

getChecked

Runtime setter

setChecked

React

Use checked for controlled state and defaultChecked for default state, and onCheckedChange for change proposals.

checked
defaultChecked
onCheckedChange

Astro

Use checked or defaultChecked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

checked
defaultChecked
starwind:checked-change
setChecked

Runtime / HTML

Use data-default-checked for initial state, listen for starwind:checked-change, and call setChecked for later updates.

data-default-checked
starwind:checked-change
setChecked

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-switch - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-checked - Reflects the checked state on the Root part.

data-filled - Reflects the filled state on the Root part.

data-unchecked - Reflects the unchecked state on the Root part.

Metadata

Attribute Value Description

data-default-checked - Reflects the default checked prop on the Root part.

data-disabled - Reflects the disabled prop on the Root part.

data-form - Reflects the form prop on the Root part.

data-id - Reflects the id prop on the Root part.

data-name - Reflects the name prop on the Root part.

data-readonly - Reflects the readonly prop on the Root part.

data-required - Reflects the required prop on the Root part.

data-unchecked-value - Reflects the unchecked value prop on the Root part.

data-value - Reflects the value prop on the Root part.

Thumb

The draggable thumb for Switch.

Default element: span
Discovery hook: data-sw-switch-thumb
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-switch-thumb - Marks the Thumb part so Starwind Runtime can find it.

Input

The native input synchronized by Switch.

Default element: input
Discovery hook: data-sw-switch-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-switch-input - Marks the Input part so Starwind Runtime can find it.

Unchecked Input

The hidden native input used when Switch submits an unchecked value.

Default element: input
Discovery hook: data-sw-switch-unchecked-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-switch-unchecked-input - Marks the Unchecked Input part so Starwind Runtime can find it.

Runtime API

Factory: createSwitch
Import: @starwind-ui/runtime/switch
Root hook: root data-sw-switch
Option props: checked, defaultChecked, disabled, form, id, name, readOnly, required, uncheckedValue, value

Runtime Setters

Method Target Description

setChecked state: checked Updates whether Switch is checked from Runtime code.

setDisabled prop: disabled Updates whether Switch is disabled from Runtime code.

setFormOptions props: form, name, required, uncheckedValue, value Updates Switch form-related options from Runtime code.

Form Participation

Fact	Value
Form props	form, id, name, required, uncheckedValue, value
Hidden input	input (checkbox)
Field integration	Yes

Component Relationship

Switch Direct primitive

Changelog

View version history v1.0.0 3 releases

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.

Layer Metadata

Switch Primitive uses createSwitch. Styled components: Switch.

primitive Switch Primitive Switch Primitive uses createSwitch. Styled components: Switch. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters switch Switch Single Boolean Control Controls with a single checked, pressed, or enabled state. /docs/primitives/switch/ createSwitch @starwind-ui/runtime/switch /docs/runtime/#create-switch root checked defaultChecked disabled form id name readOnly required uncheckedValue value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Switch data-sw-* contract yourself, then initialize createSwitch. html Use the Astro primitive adapter to render Switch anatomy with the Runtime wiring included. Use the React primitive adapter when Switch state participates in React rendering. tsx span data-sw-switch boolean Controls whether Switch is checked. Sets whether Switch starts checked for uncontrolled usage. Disables the Root part. string Associates the control with a form element. Sets the id used by the associated native control. Sets the submitted form field name. nativeButton Renders the control as a native button element. Marks the control as read-only. Marks the form control as required. Sets the value submitted when the checkbox is unchecked. Controls the current Switch value. onCheckedChange (checked: boolean, details: SwitchCheckedChangeDetails) => void SwitchCheckedChangeDetails Runs when the Switch checked state changes. 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 Reflects the disabled prop on the Root part. data-filled Reflects the filled state on the Root part. data-form Reflects the form prop on the Root part. data-id Reflects the id prop on the Root part. data-name Reflects the name prop on the Root part. data-readonly Reflects the readonly prop on the Root part. data-required Reflects the required prop on the Root part. data-unchecked Reflects the unchecked state on the Root part. data-unchecked-value Reflects the unchecked value prop on the Root part. data-value Reflects the value prop on the Root part. getChecked setChecked checkedChange starwind:checked-change setDisabled setFormOptions form, name, required, uncheckedValue, value thumb data-sw-switch-thumb Marks the Thumb part so Starwind Runtime can find it. input data-sw-switch-input Marks the Input part so Starwind Runtime can find it. uncheckedInput data-sw-switch-unchecked-input Marks the Unchecked Input part so Starwind Runtime can find it. Root aria-checked aria-readonly aria-required Thumb Input type aria-hidden tabIndex Unchecked Input @starwind-ui/astro @starwind-ui/astro/switch Render uncontrolled initial checked state; runtime owns updates after hydration. @starwind-ui/react @starwind-ui/react/switch Bridge controlled checked updates through setChecked and resync uncontrolled state after form resets. /docs/components/switch/ Direct primitive direct-primitive Styled component Switch

Switch Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Thumb

Data Attributes

Runtime hooks

Input

Data Attributes

Runtime hooks

Unchecked Input

Data Attributes

Runtime hooks

Runtime API

Runtime Setters

Form Participation

Related Styled Components

Changelog

v1.0.0

v0.1.1

v0.1.0