# Toggle

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Toggle } from "@/components/starwind/toggle";
---

<Toggle variant="outline">Toggle</Toggle>
```
  </div>
  <div slot="react">
```tsx
import { Toggle } from "@/components/starwind/toggle";

export function Example() {
  return (
    <>
      <Toggle variant="outline">Toggle</Toggle>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add toggle
```

## Usage

### variant

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

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

### size

```astro
---
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.

```astro
---
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`.

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

> **Info:** 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.

## Framework Availability
Toggle is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### Toggle
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultPressed` | `boolean` | No | - | Primitive override | Sets the initial pressed state when the control is uncontrolled. |
| `nativeButton` | `boolean` | No | - | Primitive override | Uses native button semantics for the interactive control. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `variant` | `"default" \| "outline"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Toggle Primitive](/docs/primitives/toggle/)
- Runtime factory: [`createToggle`](/docs/runtime/#create-toggle) 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](/docs/primitives/toggle/) 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