On this page

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 toggle

npx starwind@latest add toggle

yarn dlx starwind@latest add toggle

Framework Availability

Astro Available React Available

Toggle is available for Astro and React.

Usage

variant

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

<Toggle variant="default">Default</Toggle>
<Toggle variant="outline">Outline</Toggle>

size

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

<Toggle size="sm">Small</Toggle>
<Toggle size="md">Medium</Toggle>
<Toggle size="lg">Large</Toggle>

syncGroup

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>

Event Handling

Whenever toggled, the Toggle root emits starwind:pressed-change. Read the next state from event.detail.pressed.

Toggle is currently: off

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

Runtime example adjustment

Event listeners now attach to the Toggle root and use starwind:pressed-change; the legacy component-specific event is retained only as a compatibility detail.

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.

Toggle

Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.

Contains the following additional props:

Prop Type Default

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

Toggle Primitive

Runtime API

Toggle primitive: createToggle from @starwind-ui/runtime/toggle

Changelog

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

v1.0.1

Add starwind:init event 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