Toggle
---import { Toggle } from "@/components/starwind/toggle";---
<Toggle variant="outline">Toggle</Toggle>import { Toggle } from "@/components/starwind/toggle";
export function Example() { return ( <> <Toggle variant="outline">Toggle</Toggle> </> );}Installation
pnpx starwind@latest add togglenpx starwind@latest add toggleyarn dlx starwind@latest add toggleUsage
---import { Toggle } from "@/components/starwind/toggle";---
<Toggle variant="outline">Toggle</Toggle>import { Toggle } from "@/components/starwind/toggle";
export function Example() { return ( <> <Toggle variant="outline">Toggle</Toggle> </> );}Variants
---import { Toggle } from "@/components/starwind/toggle";---
<Toggle variant="default">Default</Toggle><Toggle variant="outline">Outline</Toggle>import { Toggle } from "@/components/starwind/toggle";
export function Example() { return ( <> <Toggle variant="default">Default</Toggle> <Toggle variant="outline">Outline</Toggle> </> );}Sizes
---import { Toggle } from "@/components/starwind/toggle";---
<Toggle size="sm">Small</Toggle><Toggle size="md">Medium</Toggle><Toggle size="lg">Large</Toggle>import { Toggle } from "@/components/starwind/toggle";
export function Example() { return ( <> <Toggle size="sm">Small</Toggle> <Toggle size="md">Medium</Toggle> <Toggle size="lg">Large</Toggle> </> );}Synced Groups
Use the syncGroup prop to keep multiple toggles in sync. When one toggle in the group is pressed, all toggles with the same syncGroup will mirror its state.
---import { Toggle } from "@/components/starwind/toggle";---
<Toggle variant="outline" syncGroup="view-mode"> Grid view</Toggle><Toggle variant="outline" syncGroup="view-mode"> Grid view (mirrored)</Toggle>import { Toggle } from "@/components/starwind/toggle";
export function Example() { return ( <> <Toggle variant="outline" syncGroup="view-mode"> Grid view </Toggle> <Toggle variant="outline" syncGroup="view-mode"> Grid view (mirrored) </Toggle> </> );}Event Handling
Whenever toggled, the Toggle root emits starwind:pressed-change. Read the next state from event.detail.pressed.
---import { Toggle } from "@/components/starwind/toggle";---
<div class="space-y-4"> <Toggle id="test-toggle">Test Toggle</Toggle>
<div id="status-display" class="text-muted-foreground text-sm"> Toggle is currently: <span class="text-foreground font-medium">off</span> </div></div>
<script> const root = document.querySelector<HTMLElement>("#test-toggle"); const output = document.querySelector<HTMLElement>("#status-display span");
root?.addEventListener("starwind:pressed-change", (event) => { const { pressed } = (event as CustomEvent<{ pressed: boolean }>).detail; if (output) output.textContent = pressed ? "on" : "off"; });</script>import { useState } from "react";import { Toggle } from "@/components/starwind/toggle";
export function Example() { const [pressed, setPressed] = useState(false);
return ( <div className="space-y-4"> <Toggle pressed={pressed} onPressedChange={setPressed}>Test Toggle</Toggle> <div className="text-muted-foreground text-sm"> Toggle is currently:{" "} <span className="text-foreground font-medium">{pressed ? "on" : "off"}</span> </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.
Toggle
Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.
Contains the following additional props:
defaultPressed boolean —
- Description
- Sets the initial pressed state when the control is uncontrolled.
- Classification
- Primitive override
- Primitive prop
- toggle.Root.defaultPressed
nativeButton boolean —
- Description
- Uses native button semantics for the interactive control.
- Classification
- Primitive override
- Primitive prop
- toggle.Root.nativeButton
size "sm" | "md" | "lg" "md"
- Description
- Selects the component's visual size.
- Classification
- Styled variant
variant "default" | "outline" "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 Toggle.
Primitive API
Runtime API
- Toggle primitive
createTogglefrom@starwind-ui/runtime/toggle
Changelog
View version history v2.0.1 5 releases
v2.0.1
- Updated React Runtime state synchronization so canceled proposals stay uncommitted and accepted changes remain aligned.
v2.0.0
- Rebuilt Toggle on Starwind Runtime for pressed state and pressed-change events.
- See the Toggle Primitive for the underlying unstyled anatomy and behavior API.
v1.0.3
- Refactor tailwind variants functions into separate
variants.tsfile
v1.0.1
- Add
starwind:initevent listener to enable initialization of additional Toggles loaded after an initial page load, such as when using server islands
v1.0.0
- Initial release with starwind v1.12.0