Switch
--- import { Switch } from "@/components/starwind/switch"; ---
<Switch id="demo-switch" label="Switch" />import { Switch } from "@/components/starwind/switch";
export function Example() { return ( <> <Switch id="demo-switch" label="Switch" /> </> );}Installation
pnpx starwind@latest add switchnpx starwind@latest add switchyarn dlx starwind@latest add switchFramework Availability
Astro Available React AvailableSwitch is available for Astro and React.
Usage
variant
---import { Switch } from "@/components/starwind/switch";---
<Switch id="default" label="Default" variant="default" defaultChecked /><Switch id="primary" label="Primary" variant="primary" defaultChecked /><Switch id="secondary" label="Secondary" variant="secondary" defaultChecked /><Switch id="info" label="Info" variant="info" defaultChecked /><Switch id="success" label="Success" variant="success" defaultChecked /><Switch id="warning" label="Warning" variant="warning" defaultChecked /><Switch id="error" label="Error" variant="error" defaultChecked />Runtime example adjustment
Mutable Astro examples use defaultChecked so the Runtime owns subsequent state changes. Reserve checked for controlled framework adapters that resynchronize the value.
size
---import { Switch } from "@/components/starwind/switch";---
<Switch id="small" label="Small" size="sm" /><Switch id="medium" label="Medium" size="md" /><Switch id="large" label="Large" size="lg" />Event Handling
Whenever toggled, the Switch root emits starwind:checked-change. Read the next state from event.detail.checked.
Switch Event Test
---import { Switch } from "@/components/starwind/switch";---
<div class="mt-8 space-y-4"> <h2 class="text-xl font-semibold">Switch Event Test</h2>
<div class="space-y-4"> <Switch id="test-switch" label="Test Switch" variant="primary" />
<div id="status-display" class="text-muted-foreground text-sm"> Switch is currently: <span class="text-foreground font-medium">off</span> </div> </div></div>
<script> const root = document.querySelector<HTMLElement>("#test-switch"); const output = document.querySelector<HTMLElement>("#status-display span");
root?.addEventListener("starwind:checked-change", (event) => { const { checked } = (event as CustomEvent<{ checked: boolean }>).detail; if (output) output.textContent = checked ? "on" : "off"; });</script>Runtime example adjustment
Event listeners now attach to the Switch root and use the shared starwind:checked-change contract. The legacy component-specific event and exported event type are no longer required.
API Reference
Styled Component API
These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.
Switch
Inherits button attributes. Omits `aria-checked`, `defaultChecked`, `onChange`, `role`, and `type`.
Contains the following additional props:
defaultChecked boolean —
- Description
- Sets the initial checked state when the choice is uncontrolled.
- Classification
- Primitive override
- Primitive prop
- switch.Root.defaultChecked
id Required string —
- Description
- Sets the element id used by labels and related controls.
- Classification
- Primitive override
- Primitive prop
- switch.Root.id
label string —
- Description
- Provides accessible text for the component.
- Classification
- Wrapper prop
padding number —
- Description
- Sets the component's internal padding.
- Classification
- Wrapper prop
size "sm" | "md" | "lg" "md"
- Description
- Selects the component's visual size.
- Classification
- Styled variant
variant "primary" | "secondary" | "default" | "info" | "success" | "warning" | "error" "default"
- Description
- Selects the component's visual variant.
- Classification
- Styled variant
Primitive And Runtime API
Use these references when you need the lower-level behavior APIs behind Switch.
Primitive API
Runtime API
- Switch primitive
createSwitchfrom@starwind-ui/runtime/switch
Changelog
v2.0.0
- Rebuilt Switch on Starwind Runtime for checked state, native form participation, and checked-change events.
- See the Switch Primitive for the underlying unstyled anatomy and behavior API.
v1.3.3
- Refactor tailwind variants functions into separate
variants.tsfile
v1.3.1
- Add
starwind:initevent listener to enable initialization of additional Switches loaded after an initial page load, such as when using server islands
v1.3.0
- style and focus state updates
v1.2.0
- Add a
data-slotattribute to all components to enable global styling updates
v1.1.0
tailwind-variantsnow implemented. This usestailwind-mergeunder the hood to merge Tailwind classes without style conflicts, allowing you to override any existing classes using the “class” prop.