Theme Toggle
Free · MITHeadless, accessible, and styled entirely through the attribute surface below — bring your own CSS system, or start from the reference theme.
Install
Without a flag you get no styling at all — plain HTML carrying the attribute surface below. --theme copies the same theme in two dialects;--bridge lumos re-points either one onto Lumos for Astro's tokens (it needs a theme to re-point, and Lumos itself, already in your project).
Unstyled — behavior only, you write the CSS
npx astrocraft-ui add utility/theme-togglePlain-CSS theme — no build step
npx astrocraft-ui add utility/theme-toggle --theme cssTailwind theme — needs Tailwind v4
npx astrocraft-ui add utility/theme-toggle --theme tailwindPlain-CSS theme, re-pointed onto Lumos tokens
npx astrocraft-ui add utility/theme-toggle --theme css --bridge lumosTailwind theme, re-pointed onto Lumos tokens
npx astrocraft-ui add utility/theme-toggle --theme tailwind --bridge lumosLive demo
ThemeToggle
The one sanctioned class-write in the library: it flips .darkon <html> and persists the pick in localStorage. This page is watching it — toggle and the whole demo sheet follows.
Attribute surface
With no class-merging machinery, these attributes are the whole extension point. State is a data-attribute or a native attribute; visibility is the hiddenattribute. Generated from source by pnpm slots.
| Component | Slots | Variants | Runtime state | Native state |
|---|---|---|---|---|
| `ThemeToggle.astro` | `theme-toggle` `theme-toggle-moon` `theme-toggle-sun` | `data-variant`: `primary` · `secondary` · `outline` · `ghost` `data-size`: `sm` · `md` · `lg` | — | — |
Source
What the command copies — 2 files, alias-free so the copy lands standing alone. This is the whole component; there is nothing else.
---
// src/components/ui/utility/theme-toggle/ThemeToggle.astro — headless primitive (see ../../README.md).
// A manual light/dark override. The sun/moon flip is CSS-only, keyed on the `.dark` class on <html>
// (structure.css carries those two display rules) — so it is correct pre-paint with no flash, given a
// pre-paint script that sets `.dark` before first render. Only the click needs JS: toggle `.dark`,
// persist the pick to localStorage("colorTheme"), and keep `aria-pressed` accurate.
//
// `.dark` is the ONE class this library touches, and deliberately so: it is a plain convention on the
// root element that every CSS system can hook, not a Tailwind utility. Do not "headless" it into a
// data attribute — that breaks every consumer's muscle memory for no gain. It is also the one
// expected `classList` hit in the no-classes-from-JS check (see ../../README.md).
//
// Pair it with a pre-paint inline script in your <head> that reads localStorage("colorTheme") and
// falls back to `prefers-color-scheme` — `src/layouts/BaseLayout.astro` has a copyable one.
import "../../../../styles/structure.css";
import type { HTMLAttributes } from "astro/types";
type Props = HTMLAttributes<"button"> & {
variant?: "primary" | "secondary" | "outline" | "ghost";
size?: "sm" | "md" | "lg";
};
const { variant = "ghost", size = "sm", class: className, ...rest } = Astro.props;
---
<button
type="button"
data-slot="theme-toggle"
data-variant={variant}
data-size={size}
aria-label="Toggle color theme"
class={className}
{...rest}
>
<slot name="sun"
><svg
data-slot="theme-toggle-sun"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
aria-hidden="true"
>
<circle cx="12" cy="12" r="4"></circle>
<path d="M12 2v2"></path>
<path d="M12 20v2"></path>
<path d="m4.93 4.93 1.41 1.41"></path>
<path d="m17.66 17.66 1.41 1.41"></path>
<path d="M2 12h2"></path>
<path d="M20 12h2"></path>
<path d="m6.34 17.66-1.41 1.41"></path>
<path d="m19.07 4.93-1.41 1.41"></path>
</svg></slot
>
<slot name="moon"
><svg
data-slot="theme-toggle-moon"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
aria-hidden="true"
>
<path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path>
</svg></slot
>
</button>
<script>
import { onReadyOnce } from "../../_once";
// `aria-pressed` is intentionally NOT in the static markup: the initial theme is client-determined
// pre-paint (BaseHead), so any SSR value would be wrong for dark-mode users. `sync()` sets the truthful
// value on wire (load + each astro:after-swap). Don't "fix" this by hardcoding aria-pressed="false".
function wire(btn: HTMLElement) {
const sync = () =>
btn.setAttribute("aria-pressed", String(document.documentElement.classList.contains("dark")));
sync();
btn.addEventListener("click", () => {
const dark = document.documentElement.classList.toggle("dark");
try {
localStorage.setItem("colorTheme", dark ? "dark" : "light");
} catch {
// storage blocked (sandboxed iframe, site data off) — the visual toggle still applies for this
// session; it just won't persist across navigations. Fall through so aria-pressed stays in sync.
}
sync();
});
}
onReadyOnce('[data-slot="theme-toggle"]', wire);
</script>
import ThemeToggle from "./ThemeToggle.astro";
export { ThemeToggle };
export default ThemeToggle;
What you get
The component source, copied into your project by npx astrocraft-ui add utility/theme-toggle — no package dependency, no CSS to fight. Whatever the paid blocks compose, this is it.