# Theme Toggle
```astro
---
import { ThemeToggle } from "@/components/starwind/theme-toggle";
---
```
```tsx
import { ThemeToggle } from "@/components/starwind/theme-toggle";
export function Example() {
return (
<>
);
}
```
```vue
```
> **Info:** Theme Toggle now uses the shared theme controller from `@starwind-ui/astro/theme`. Controls with
the same sync group stay aligned across navigation and system-theme changes.
## Installation
```bash
npx starwind@latest add theme-toggle --framework astro
```
```bash
npx starwind@latest add theme-toggle --framework react
```
```bash
npx starwind@latest add theme-toggle --framework vue
```
## Usage
```astro
---
import { ThemeToggle } from "@/components/starwind/theme-toggle";
---
```
```tsx
import { ThemeToggle } from "@/components/starwind/theme-toggle";
export function Example() {
return (
<>
);
}
```
```vue
```
## Preventing a theme flash
Render `ThemeInitScript` in your document head. It applies the persisted or system theme before
the page becomes visible.
```astro
---
import { ThemeInitScript } from "@starwind-ui/astro/theme";
---
```
```tsx
import type { ReactNode } from "react";
import { getThemeInitScript } from "@starwind-ui/react/theme";
function ThemeInitScript() {
return ;
}
export function RootLayout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```vue
```
## Custom icons
```astro
---
import Heart from "@tabler/icons/outline/heart.svg";
import Star from "@tabler/icons/outline/star.svg";
import { ThemeToggle } from "@/components/starwind/theme-toggle";
---
```
```tsx
import { IconHeart as Heart, IconStar as Star } from "@tabler/icons-react";
import { ThemeToggle } from "@/components/starwind/theme-toggle";
export function Example() {
return (
}
darkIcon={
}
/>
);
}
```
```vue
```
> **Info:** Custom icon visibility follows the Runtime-owned `data-state` and `data-ready` attributes. Keep
`data-theme-icon` on each icon so the controller can synchronize it.
## API Reference
### ThemeToggle
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `ariaLabel` | `string` | No | `"Toggle theme"` | Wrapper prop | Provides an accessible label when visible text is not available. |
| `defaultPressed` | `boolean` | No | - | Wrapper prop | Sets the initial pressed state when the control is uncontrolled. |
| `disabled` | `boolean` | No | `false` | Wrapper prop | Disables interaction with the component. |
| `pressed` | `boolean` | No | - | Wrapper prop | Controls the pressed state. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `syncGroup` | `string` | No | `"starwind-theme"` | Wrapper prop | Synchronizes pressed state across Theme Toggles in the same named group. |
| `value` | `string` | No | - | Wrapper prop | Controls or identifies the component value. |
| `variant` | `"default" \| "outline"` | No | `"outline"` | Styled variant | Selects the component's visual variant. |
- Inherits button attributes. Omits `aria-pressed`, `defaultPressed`, `disabled`, `onChange`, `type`, and `value`.
## Changelog
### v2.0.0
- Added contract-generated Astro and React implementations and replaced page-local storage logic with the shared Runtime theme controller and `ThemeInitScript`.
- See the [Runtime theme reference](/docs/runtime/#theme) for the shared theme behavior and helpers.
- Theme Toggle now uses the shared theme controller from `@starwind-ui/astro/theme`. Controls with
the same sync group stay aligned across Astro navigation and system-theme changes.