On this page

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

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

---
import { Toggle } from "@starwind-ui/astro/toggle";
---

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

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

import { Toggle } from "@starwind-ui/react/toggle";

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

Render the Toggle data-sw-* contract yourself, then initialize createToggle.

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

Default element: button
Discovery hook: data-sw-toggle
Role: -

Props

Prop Type Default

pressed boolean -

Description

Controls the pressed state for Toggle.

Kind

control

Targets

Full type

boolean

React

Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.

pressed
defaultPressed
onPressedChange

Astro

Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.

pressed
defaultPressed
starwind:pressed-change
setPressed

Runtime / HTML

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

data-default-pressed
starwind:pressed-change
setPressed

defaultPressed boolean false

Description

Controls the default pressed state for Toggle.

Kind

control

Targets

Full type

boolean

React

Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.

pressed
defaultPressed
onPressedChange

Astro

Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.

pressed
defaultPressed
starwind:pressed-change
setPressed

Runtime / HTML

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

data-default-pressed
starwind:pressed-change
setPressed

disabled boolean false

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

nativeButton boolean true

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

syncGroup string -

Description: Configures the sync group option for the Root part.
Kind: option
Targets: -
Full type: string

value string -

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

onPressedChange (pressed: boolean, details: TogglePressedChangeDetails) => void -

Description

Runs when on pressed change changes for Toggle.

Kind

callback

Targets

Full type

(pressed: boolean, details: TogglePressedChangeDetails) => void

React

Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.

pressed
defaultPressed
onPressedChange

Astro

Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.

pressed
defaultPressed
starwind:pressed-change
setPressed

Runtime / HTML

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

data-default-pressed
starwind:pressed-change
setPressed

Events

Event Callback Value

pressedChange onPressedChange pressed: boolean

Description

Fires when the pressed state changes for Toggle.

DOM event

starwind:pressed-change

Details type

TogglePressedChangeDetails

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

pressed boolean pressed / defaultPressed

Description

Tracks whether Toggle is pressed.

Initial attribute

data-default-pressed

Runtime getter

getPressed

Runtime setter

setPressed

React

Use pressed for controlled state and defaultPressed for default state, and onPressedChange for change proposals.

pressed
defaultPressed
onPressedChange

Astro

Use pressed or defaultPressed for initial state, listen for starwind:pressed-change, and call setPressed for later updates.

pressed
defaultPressed
starwind:pressed-change
setPressed

Runtime / HTML

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

data-default-pressed
starwind:pressed-change
setPressed

Data Attributes

Runtime hooks

Attribute Value Description

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

State

Attribute Value Description

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

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

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

Metadata

Attribute Value Description

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

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

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

data-sync-group - Reflects the sync group prop on the Root part.

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

Runtime API

Factory: createToggle
Import: @starwind-ui/runtime/toggle
Root hook: root data-sw-toggle
Option props: defaultPressed, disabled, nativeButton, pressed, syncGroup, value

Runtime Setters

Method Target Description

setPressed state: pressed Updates whether Toggle is pressed from Runtime code.

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

Component Relationship

Toggle Direct primitive

Toggle Group Composite

Changelog

View version history v1.0.0 4 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.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.

Layer Metadata

Toggle Primitive uses createToggle. Styled components: Toggle and Toggle Group.

primitive Toggle Primitive Toggle Primitive uses createToggle. Styled components: Toggle and Toggle Group. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters toggle Toggle Single Boolean Control Controls with a single checked, pressed, or enabled state. /docs/primitives/toggle/ createToggle @starwind-ui/runtime/toggle /docs/runtime/#create-toggle root defaultPressed disabled nativeButton pressed syncGroup value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Toggle data-sw-* contract yourself, then initialize createToggle. html Use the Astro primitive adapter to render Toggle anatomy with the Runtime wiring included. Use the React primitive adapter when Toggle state participates in React rendering. tsx button data-sw-toggle boolean Controls the pressed state for Toggle. Controls the default pressed state for Toggle. Disables the Root part. Renders the control as a native button element. string Configures the sync group option for the Root part. Controls the current Toggle value. onPressedChange (pressed: boolean, details: TogglePressedChangeDetails) => void TogglePressedChangeDetails Runs when on pressed change changes for 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 Reflects the disabled prop on the Root part. data-native Reflects the native prop on the Root part. data-pressed state Reflects the pressed state on the Root part. data-state Reflects the current state on the Root part. data-sync-group Reflects the sync group prop on the Root part. data-unpressed Reflects the unpressed state on the Root part. data-value Reflects the value prop on the Root part. getPressed setPressed pressedChange starwind:pressed-change setDisabled Root aria-disabled aria-pressed @starwind-ui/astro @starwind-ui/astro/toggle Render uncontrolled initial pressed state; runtime owns updates after hydration. @starwind-ui/react @starwind-ui/react/toggle Bridge controlled pressed updates through setPressed with sync enabled for sync groups. /docs/components/toggle/ Direct primitive direct-primitive Styled component Toggle toggle-group Toggle Group /docs/components/toggle-group/ Composite composite The styled toggle group combines group-level behavior with individual toggle items. Styled component Toggle Group

Toggle Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Runtime API

Runtime Setters

Related Styled Components

Changelog

v1.0.0

v0.1.2

v0.1.1

v0.1.0