Dark Mode

Starwind Pro blocks use the Starwind UI v3 theme controller. Tailwind CSS dark: styles become active when the controller places the dark class on <html>.

Initialize the theme

Render ThemeInitScript in the <head> of your main Astro layout. It applies the saved or system theme before the page becomes visible.

1
---
2
import { ThemeInitScript } from "@starwind-ui/astro/theme";
3
---
4

5
<!doctype html>
6
<html lang="en">
7
  <head>
8
    <ThemeInitScript />
9
  </head>
10
  <body>
11
    <slot />
12
  </body>
13
</html>

The default initializer uses the colorTheme local storage key. It accepts light, dark, or system, and uses system when no valid preference exists. It also reapplies the theme after Astro view transitions.

Info

You do not need a separate astro:after-swap theme script. ThemeInitScript handles Astro navigation and system preference changes.

Add a theme control

Use the Starwind UI Theme Toggle for a light and dark control.

1
---
2
import { ThemeToggle } from "@/components/starwind/theme-toggle";
3
---
4

5
<ThemeToggle ariaLabel="Toggle theme" />

For a light, dark, and system picker, use a Starwind Pro theme switcher or the shared controller:

1
import { initThemeController } from "@starwind-ui/astro/theme";
2

3
const theme = initThemeController();
4
theme.setTheme("system");

Custom controls can listen for starwind:theme-change. Keep the initializer and controller on the same storage key and class name when you change their defaults.

See the current Starwind UI Dark Mode guide for the full controller contract.