On this page

Switch Primitive

Switch is a Starwind Runtime primitive in the single-boolean-control contract family.

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

defaultChecked boolean false

Description: Sets whether Switch starts checked for uncontrolled usage.
Kind: control
Targets: -
Full type: boolean

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

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: -
Cancelable: No

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
State control support: React supports controlled and default state with checked and defaultChecked props. Runtime/HTML reads initial state from data-default-checked, emits starwind:checked-change, and updates with setChecked. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.

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

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