Skip to content

Theme switch

Light or Dark, following the system until the person chooses, then remembered in this browser.

<div class="cap-specimen-row">
  <fieldset class="cap-theme">
    <legend class="cap-sr-only">Theme</legend>
    <div class="cap-theme-options">
      <label><input type="radio" name="t-hover" value="light" checked /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="3" /><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1 1M11.6 11.6l1 1M3.4 12.6l1-1M11.6 4.4l1-1" /></svg><span class="cap-theme-text">Light</span></label>
      <label><input type="radio" name="t-hover" value="dark" /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><path d="M13.5 9.3A5.5 5.5 0 0 1 6.7 2.5a5.5 5.5 0 1 0 6.8 6.8z" /></svg><span class="cap-theme-text">Dark</span></label>
    </div>
  </fieldset>
  <fieldset class="cap-theme">
    <legend class="cap-sr-only">Theme</legend>
    <div class="cap-theme-options">
      <label><input type="radio" name="t-disabled" value="light" checked /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="3" /><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1 1M11.6 11.6l1 1M3.4 12.6l1-1M11.6 4.4l1-1" /></svg><span class="cap-theme-text">Light</span></label>
      <label><input type="radio" name="t-disabled" value="dark" disabled /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><path d="M13.5 9.3A5.5 5.5 0 0 1 6.7 2.5a5.5 5.5 0 1 0 6.8 6.8z" /></svg><span class="cap-theme-text">Dark</span></label>
    </div>
  </fieldset>
</div>
<div class="cap-specimen-row" data-density="comfortable">
  <fieldset class="cap-theme">
    <legend class="cap-sr-only">Theme</legend>
    <div class="cap-theme-options">
      <label><input type="radio" name="t-comfortable" value="light" /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="3" /><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1 1M11.6 11.6l1 1M3.4 12.6l1-1M11.6 4.4l1-1" /></svg><span class="cap-theme-text">Light</span></label>
      <label><input type="radio" name="t-comfortable" value="dark" checked /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><path d="M13.5 9.3A5.5 5.5 0 0 1 6.7 2.5a5.5 5.5 0 1 0 6.8 6.8z" /></svg><span class="cap-theme-text">Dark</span></label>
    </div>
  </fieldset>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/theme-switch.css";
import { enhance } from "capsomer/behavior/theme-switch";

enhance();

Usage

<fieldset class="cap-theme" data-cap="theme-switch">
  <legend class="cap-sr-only">Theme</legend>
  <div class="cap-theme-options">
    <label><input type="radio" name="cap-theme" value="light"><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true">[sun]</svg><span class="cap-theme-text">Light</span></label>
    <label><input type="radio" name="cap-theme" value="dark"><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true">[moon]</svg><span class="cap-theme-text">Dark</span></label>
  </div>
</fieldset>

Examples

First visit: follows the system, nothing remembered

<main class="specimen-page" tabindex="-1">
  <h1>Settings</h1>
  <fieldset class="cap-theme" data-cap="theme-switch" data-cap-pref="cap-theme-specimen-first">
    <legend class="cap-sr-only">Theme</legend>
    <div class="cap-theme-options">
      <label><input type="radio" name="theme" value="light" /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="3" /><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1 1M11.6 11.6l1 1M3.4 12.6l1-1M11.6 4.4l1-1" /></svg><span class="cap-theme-text">Light</span></label>
      <label><input type="radio" name="theme" value="dark" /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><path d="M13.5 9.3A5.5 5.5 0 0 1 6.7 2.5a5.5 5.5 0 1 0 6.8 6.8z" /></svg><span class="cap-theme-text">Dark</span></label>
    </div>
  </fieldset>
  <p>No choice made yet: the page follows the operating system's setting, and the control shows which theme that is.</p>
</main>

Light selected

<main class="specimen-page" tabindex="-1">
  <h1>Settings</h1>
  <fieldset class="cap-theme" data-cap="theme-switch" data-cap-pref="cap-theme-specimen-light">
    <legend class="cap-sr-only">Theme</legend>
    <div class="cap-theme-options">
      <label><input type="radio" name="theme" value="light" checked /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="3" /><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1 1M11.6 11.6l1 1M3.4 12.6l1-1M11.6 4.4l1-1" /></svg><span class="cap-theme-text">Light</span></label>
      <label><input type="radio" name="theme" value="dark" /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><path d="M13.5 9.3A5.5 5.5 0 0 1 6.7 2.5a5.5 5.5 0 1 0 6.8 6.8z" /></svg><span class="cap-theme-text">Dark</span></label>
    </div>
  </fieldset>
  <p>Light, whatever the operating system says.</p>
</main>

Dark selected

<main class="specimen-page" tabindex="-1">
  <h1>Settings</h1>
  <fieldset class="cap-theme" data-cap="theme-switch" data-cap-pref="cap-theme-specimen-dark">
    <legend class="cap-sr-only">Theme</legend>
    <div class="cap-theme-options">
      <label><input type="radio" name="theme" value="light" /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="3" /><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1 1M11.6 11.6l1 1M3.4 12.6l1-1M11.6 4.4l1-1" /></svg><span class="cap-theme-text">Light</span></label>
      <label><input type="radio" name="theme" value="dark" checked /><svg class="cap-theme-icon" viewBox="0 0 16 16" aria-hidden="true"><path d="M13.5 9.3A5.5 5.5 0 0 1 6.7 2.5a5.5 5.5 0 1 0 6.8 6.8z" /></svg><span class="cap-theme-text">Dark</span></label>
    </div>
  </fieldset>
  <p>Dark, whatever the operating system says.</p>
</main>

The button form, for a header: one icon button, its name says what it does, Light and Dark only

<main class="specimen-page" tabindex="-1">
  <h1>Header</h1>
  <button type="button" class="cap-theme-button" data-cap="theme-switch" data-variant="button" data-cap-pref="cap-theme-specimen-button" aria-label="Switch to dark theme">
    <svg class="cap-theme-icon" data-show="light" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5z" /></svg>
    <svg class="cap-theme-icon" data-show="dark" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="4" /><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" /></svg>
    <span class="cap-theme-tip cap-popover" data-variant="tooltip" data-side="bottom" data-offset="6" popover="manual" role="tooltip" aria-hidden="true"><span class="cap-theme-tip-text">Switch to dark theme</span><kbd>T</kbd></span>
  </button>
  <p>The moon while the page is light, the sun while it is dark. The settings page keeps the Light and Dark switch.</p>
</main>
<main class="specimen-page" tabindex="-1">
  <h1>Header</h1>
  <button type="button" class="cap-theme-button" data-cap="theme-switch" data-variant="button" data-cap-pref="cap-theme-specimen-cookie" data-cap-cookie="sample_theme" aria-label="Switch to dark theme">
    <svg class="cap-theme-icon" data-show="light" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5z" /></svg>
    <svg class="cap-theme-icon" data-show="dark" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="4" /><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" /></svg>
    <span class="cap-theme-tip cap-popover" data-variant="tooltip" data-side="bottom" data-offset="6" popover="manual" role="tooltip" aria-hidden="true"><span class="cap-theme-tip-text">Switch to dark theme</span></span>
  </button>
  <p>The page starts from the theme its server wrote. Saved: <output id="saved">nothing yet</output>.</p>
</main>

API reference

ThemeSwitch

PropTypeRequiredDoes
prefKeystringThe localStorage key; "cap-theme" by default.
legendstringThe group's name, read by a screen reader; hidden from sight in a top bar.
initialThemeChoiceWhat the server rendered (from a cookie), before the stored choice is read. Leave it out and the control shows the operating system's theme once it mounts.
cookiestringWhere a person's choice is kept besides this browser (chooseTheme in theme-switch.ts): the site's cookie, so its server renders the next page in that theme, and the site's own save for the signed-in account. With cookie the switch starts from the server's answer.
onSaveThemeSave
onError(error: unknown) => voidTold when onSave throws or rejects; the choice stands either way.

ThemeButton

PropTypeRequiredDoes
prefKeystringThe localStorage key; "cap-theme" by default.
shortcutstringThe key the app binds to toggleTheme(), shown in the tip as a key cap ("T"). The app binds it.
classNamestringExtra classes: the site header adds its own icon-control class.
initialThemeChoiceWhat the server rendered (from a cookie); leave it out and the label follows the page once it mounts. The icon follows the page by CSS either way.
cookiestring
onSaveThemeSave
onError(error: unknown) => voidTold when onSave throws or rejects; the choice stands either way.
hydratebooleanFalse on a page React never runs on in the browser: the button is written for the behavior module's enhance() to wire (its key and cookie as data-cap-pref and data-cap-cookie).

ThemeForm

PropTypeRequiredDoes
actionstringThe site's theme route: a post with theme=light or theme=dark sets the cookie and comes back.
cookiestringThe cookie the press writes with script, so the server reads the same choice; "theme" by default.
classNamestringExtra classes for both buttons: the site header adds its own icon-control class.
shortcutstringThe key the site binds to the theme, shown in the tips as a key cap. The site binds it.
prefKeystringAlso remember the choice under this localStorage key, for a part of the site whose shell reads it.

ThemeColor

PropTypeRequiredDoes
choiceThemeChoice | nullThe person's remembered choice (readThemeCookie), or null to follow the system.
ground{ light: string; dark: string }YesThe site's --ground in each theme, as literal colors.

Functions

FunctionSignatureDoes
readTheme(key?: string): ThemeChoice | nullWhat the person chose and the browser remembers, or null if they never did. A "system" remembered by 0.1.0 reads as no choice: the system's setting applies, as it did.
applyTheme(choice: ThemeChoice, opts?: { key?: string | undefined; remember?: boolean | undefined; }): voidSets data-theme, remembers the choice unless told not to, and tells every switch on the page. A person's choice (one it remembers) crossfades the page in a view transition (css/base.css), where the browser has one and motion is allowed; a restored or synced choice paints at once.
writeThemeCookie(choice: ThemeChoice, name?: string): voidWrites the site's theme cookie from the browser, Secure on https.
chooseTheme(choice: ThemeChoice, { key, cookie, onSave, onError }?: ThemeMemory, { animate }?: { animate?: boolean | undefined; }): voidA person's choice, kept everywhere the site keeps it: painted (crossfading unless animate is false), this browser's memory, the site's cookie, then the site's onSave. A save that throws or rejects goes to onError (let go without one); the page has switched and stays switched.
syncServedTheme(key?: string): voidWhere the server keeps the choice (a cookie, an account): copies the server's answer (the data-theme it wrote into the page, or none) into this browser's memory, before any switch reads it, so the two agree. With no answer the memory is cleared and the page follows the system.
applyStoredTheme(key?: string): ThemeChoice | nullApplies the remembered choice, if there is one. Run it before first paint, or the page flashes the other theme. Returns what it applied.
effectiveTheme(): ThemeChoiceThe theme the page is painting now: data-theme when set, else the operating system's. It is right even when storage cannot be read or written, because the attribute is what applyTheme sets first.
toggleTheme(key?: string, memory?: Omit<ThemeMemory, "key">): ThemeChoiceSwitches between light and dark, from whatever is showing, and keeps it as chooseTheme does (this browser, and the site's cookie and onSave when given). For a "t" shortcut.
themeButtonLabel(showing: ThemeChoice): stringThe button form says what it does, never what is showing: "Switch to dark theme" while the page is light, "Switch to light theme" while it is dark.
syncThemeButton(button: HTMLElement, showing?: ThemeChoice): voidKeeps a theme button's name and its tip's words in step with the theme that is showing.
enhance(root?: ParentNode, { onSave, onError }?: Pick<ThemeMemory, "onError" | "onSave">): () => voidAttaches to every [data-cap="theme-switch"] under root. With a remembered choice, that is checked and applied. With none and a radio checked in the markup (a server that read a cookie), that one is applied. With neither, the radio for the operating system's theme is checked and nothing is applied or remembered until the person chooses, so the page keeps following the system. A change applies and remembers; the radios follow toggleTheme(), other tabs and the system. A switch with data-cap-cookie keeps the choice in that cookie too; with a cookie or an onSave it starts from the server's answer (syncServedTheme). onSave is the site's save, handed every person's choice from every switch this attaches to; onError hears a save that fails.

Parts and data attributes

ClassIs
.cap-themethe root
.cap-theme-buttona part
.cap-theme-forma part
.cap-theme-icona part
.cap-theme-optionsa part
.cap-theme-texta part
AttributeValues
data-showdark light
StateRead from
:checkedthe platform
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform

Accessibility

KeyDoes
TabMoves to the checked choice
Left or Right arrow, Up or Down arrowChecks the other choice and applies it
tSwitches light and dark, when the app registers it
  • A fieldset named by its legend: a screen reader hears "Theme, grouping", then "Light, radio button, checked, 1 of 2".
  • The checked choice is shown by the segmented control's tint and weight, not by color alone.