Example Components

Theme Toggle

A button that switches between light and dark themes and remembers the choice, plus theme-init, which applies the saved choice before the first paint. Without a saved choice, the operating system setting applies.

Source on GitHub

Usage

Put <theme-init /> in the <head> of every page, usually through a shared head component, and <theme-toggle /> wherever the button belongs. Both need the color-scheme rules from a token stylesheet; see Theming.

Preview Source Output

examples/components/theme-toggle/theme-toggle.html

Usage HTML CSS JS

html

<theme-toggle />

html examples/components/theme-toggle/theme-toggle.html

<!-- @bascik
A button that switches between light and dark themes and remembers the choice. Needs <theme-init /> in <head> and the color-scheme rules in styles.css. Hidden until its script runs.
-->
<style>
  .toggle {
    display: inline-flex;
    align-items: center;
    gap: var(--space-2, 0.5rem);
    padding: var(--space-1, 0.25rem) var(--space-2, 0.5rem);
    border: 1px solid var(--color-border, currentColor);
    border-radius: var(--radius, 0.5rem);
    background: var(
      --color-surface,
      color-mix(in srgb, currentColor 8%, transparent)
    );
    color: inherit;
    font: inherit;
    cursor: pointer;
  }
</style>
<button class="toggle" id="toggle" type="button" hidden>Dark theme</button>
<script>
  // aria-pressed tells assistive technology whether dark theme is on; the label stays the same.
  const toggle = document.getElementById("toggle");
  const media = matchMedia("(prefers-color-scheme: dark)");
  const preview = toggle.closest("[data-demo-theme]");
  const themeTarget = preview ?? document.documentElement;
  const themeAttribute = preview ? "data-demo-theme" : "data-theme";
  const storageKey = preview ? "theme-demo" : "theme";

  if (preview) {
    try {
      const savedTheme = localStorage.getItem(storageKey);
      if (savedTheme === "light" || savedTheme === "dark")
        preview.setAttribute(themeAttribute, savedTheme);
    } catch {
      // The preview keeps its default theme when storage is unavailable.
    }
  }

  const current = () =>
    themeTarget.getAttribute(themeAttribute) ??
    (media.matches ? "dark" : "light");

  const render = () => {
    toggle.setAttribute("aria-pressed", String(current() === "dark"));
  };

  toggle.addEventListener("click", () => {
    const next = current() === "dark" ? "light" : "dark";
    themeTarget.setAttribute(themeAttribute, next);
    try {
      localStorage.setItem(storageKey, next);
    } catch {
      // Not persisted when storage is unavailable; the choice still applies here.
    }
    render();
    // Other components can react without reaching into this one.
    toggle.dispatchEvent(
      new CustomEvent("theme-change", {
        bubbles: true,
        detail: { theme: next },
      }),
    );
  });

  media.addEventListener("change", render);
  // Stay in sync when another toggle, or any other script, changes the theme.
  new MutationObserver(render).observe(themeTarget, {
    attributes: true,
    attributeFilter: [themeAttribute],
  });
  render();
  toggle.hidden = false;
</script>

HTML CSS JS

Output is shown unminified (HTML, CSS, JS, and identifier names) for readability.

The button above switches only the preview theme. It stores the choice under theme-demo, separate from the docs site's theme setting.

theme-init

html examples/components/theme-init/theme-init.html

<!-- @bascik
Applies the saved light or dark theme before first paint. Place it in <head> of every page so there is no flash of the wrong theme; its script stays in <head> and runs before the body renders. Pairs with <theme-toggle />.
-->
<!-- Tells the browser both schemes are supported before any CSS loads, so form controls and the canvas match. -->
<meta name="color-scheme" content="light dark" />
<script>
  try {
    const theme = localStorage.getItem("theme");
    if (theme === "light" || theme === "dark")
      document.documentElement.setAttribute("data-theme", theme);
  } catch {
    // Storage can be unavailable (private mode, blocked cookies). The operating system theme then applies.
  }
</script>

How It Works

theme-init runs synchronously in <head>, before the body renders, and sets data-theme on <html> from localStorage. Bascik keeps a component's script in <head> when the component is used there, so there is no flash of the wrong theme.
On a normal site, the token stylesheet reads data-theme from <html>, so switching the attribute recolors the whole page. In this preview, the toggle instead changes the preview's data-demo-theme and stores the choice under theme-demo.
The button exposes its state with aria-pressed and is hidden until its script runs.
After each change it dispatches a bubbling theme-change event, so other components can react without reaching into this one.

Adapt It

For a three-way system, light, and dark choice, use a <select> and remove the stored value for "system". See Theming.