Toggle Primitive
Toggle is a Starwind Runtime primitive in the single-boolean-control contract family.
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 Toggle
pressed boolean -
- Description
- Controls the pressed state for Toggle.
- Kind
- control
- Targets
- -
- Full type
- boolean
defaultPressed boolean false
- Description
- Controls the default pressed state for Toggle.
- Kind
- control
- Targets
- -
- Full type
- boolean
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: unknown, details: TogglePressedChangeDetails) => void -
- Description
- Runs when on pressed change changes for Toggle.
- Kind
- callback
- Targets
- -
- Full type
- (pressed: unknown, details: TogglePressedChangeDetails) => void
Events
Event Callback Value Toggle
pressedChange onPressedChange pressed
- Description
- Fires when the pressed state changes for Toggle.
- DOM event
- starwind:pressed-change
- Details type
- TogglePressedChangeDetails
- Timing
- -
- Cancelable
- No
State
State Type Props Toggle
pressed boolean pressed / defaultPressed
- Description
- Tracks whether Toggle is pressed.
- Initial attribute
- data-default-pressed
- Runtime getter
- getPressed
- Runtime setter
- setPressed
- State control support
- 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.
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.
Related Styled Components
Component Relationship
Toggle Direct primitive
Toggle Group Composite