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 switchUsage
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 />import { Switch } from "@/components/starwind/switch";
export function Example() { return ( <> <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 /> </> );}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" />import { Switch } from "@/components/starwind/switch";
export function Example() { return ( <> <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>import { useState } from "react";import { Switch } from "@/components/starwind/switch";
export function Example() { const [checked, setChecked] = useState(false);
return ( <div className="mt-8 space-y-4"> <h2 className="text-xl font-semibold">Switch Event Test</h2> <div className="space-y-4"> <Switch id="test-switch" label="Test Switch" variant="primary" checked={checked} onCheckedChange={setChecked} /> <div className="text-muted-foreground text-sm"> Switch is currently:{" "} <span className="text-foreground font-medium">{checked ? "on" : "off"}</span> </div> </div> </div> );}API Reference
Styled Component API
These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. 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.1
- Updated React Runtime state synchronization so canceled proposals stay uncommitted and accepted changes remain aligned.
- Associated the React Switch with its native form owner for submission and reset behavior.
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.