Skip to main content

Starwind UI v3.0 is now available! Migration guide

Installation

Usage

---
import { Toggle } from "@/components/starwind/toggle";
---
<Toggle variant="outline">Toggle</Toggle>

Variants

Sizes

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.

Event Handling

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

Toggle is currently: off

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:

Prop Type Default Toggle details
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
createToggle from @starwind-ui/runtime/toggle

Changelog

View version history v2.1.0 7 releases

v2.1.0

  • In Svelte, a defined pressed that you pass when Toggle mounts now stays under your control, as in React and Vue. To change it, use bind: or update your state in the change callback. A form reset keeps it. If you pass undefined at mount, Toggle keeps its own state.
  • In Vue, a Boolean prop that you leave out, such as defaultPressed or nativeButton, no longer becomes false. The default of the underlying component applies.
  • Fixed a Toggle trigger on a link or span that stayed disabled when a framework wrote disabled="false". On a native form control, any disabled attribute still disables it.

v2.0.2

  • React toggles inside Toggle Group now start with the group’s selected and disabled state.

v2.0.1

  • In React, you can cancel a change before it applies. The component then keeps its previous state, and it shows only the changes that apply.

v2.0.0

  • Toggle now gets its behavior from Starwind Runtime. Runtime handles the pressed state and pressed-change events.
  • See the Toggle Primitive for the unstyled parts and the behavior API.

v1.0.3

  • The Tailwind variants now live in their own variants.ts file in the component folder.

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