On this page

Theme Toggle

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

    <ThemeToggle ariaLabel="Toggle theme" />

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

export function Example() {
  return (
    <>
      <ThemeToggle ariaLabel="Toggle theme" />
    </>
  );
}

Runtime example adjustment

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.

Installation

pnpx starwind@latest add theme-toggle

npx starwind@latest add theme-toggle

yarn dlx starwind@latest add theme-toggle

Framework Availability

Astro Available React Available

Theme Toggle is available for Astro and React.

Usage

Preventing a theme flash

Render ThemeInitScript in your document head. It applies the persisted or system theme before the page becomes visible.

---
import { ThemeInitScript } from "@starwind-ui/astro/theme";
---

<html>
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <slot />
  </body>
</html>

Custom icons

---
import Heart from "@tabler/icons/outline/heart.svg";
import Star from "@tabler/icons/outline/star.svg";
import { ThemeToggle } from "@/components/starwind/theme-toggle";
---

<ThemeToggle ariaLabel="Toggle theme with custom icons">
  <Heart
    slot="light-icon"
    class="hidden size-5 group-data-[state=off]:data-ready:block"
    data-theme-icon
  />
  <Star
    slot="dark-icon"
    class="hidden size-5 group-data-[state=on]:data-ready:block"
    data-theme-icon
  />
</ThemeToggle>

Runtime example adjustment

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

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.

Theme Toggle

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

Contains the following additional props:

Prop Type Default

ariaLabel string "Toggle theme"

Description: Provides an accessible label when visible text is not available.
Classification: Wrapper prop

defaultPressed boolean —

Description: Sets the initial pressed state when the control is uncontrolled.
Classification: Wrapper prop

disabled boolean false

Description: Disables interaction with the component.
Classification: Wrapper prop

pressed boolean —

Description: Controls the pressed state.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

syncGroup string "starwind-theme"

Description: Synchronizes pressed state across Theme Toggles in the same named group.
Classification: Wrapper prop

value string —

Description: Controls or identifies the component value.
Classification: Wrapper prop

variant "default" | "outline" "outline"

Description: Selects the component's visual variant.
Classification: Styled variant

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 for the shared theme behavior and helpers.