Skip to main content

Scheme-switcher

A consumer-facing color-scheme control. A single button cycles through three preferences - Light, Dark, and System - and applies the result to the page. Light and dark are written explicitly; system follows the operating system and updates live when the OS preference changes. Built on the cycle utility in show mode.

Usage​

When to use

  • Giving a reader a color-scheme choice the site remembers between visits
  • Offering an explicit override on a site that otherwise follows the operating system
  • Anywhere a consumer already expects the control - a header, a footer, a settings menu

When not to use

  • As the only way the site reaches dark mode - the head snippet below has to apply the stored preference before the first paint either way
  • For any preference other than the color scheme - the control writes data-color-scheme and nothing else
  • On a page that ships a single scheme; a control with one destination says the site has a choice it does not have

Do

  • Place it where a reader looks for settings, and in the same position on every page
  • Keep the visually hidden Color scheme: prefix so the button announces what it changes
  • Ship the head snippet alongside it, so the stored preference wins the first paint

Don't

  • Add a fourth option - light, dark and system are the whole set, and system is a preference rather than a third scheme
  • Write data-color-scheme anywhere but <html>; a stray attribute lower in the tree resolves to nothing
  • Rely on the icon alone to say which scheme is active - the label carries the meaning

Placing the control. It is self-contained: the JavaScript reads the stored preference, applies the resolved scheme to <html>, and persists every change. By default it shows icons only; the text labels stay available to assistive technology and can be revealed with has_labels.

<button type="button" class="scheme-switcher" data-scheme-switcher data-cycle="show" data-cycle-current="system">
<span class="scheme-switcher-option" data-cycle-value="light" hidden>
<svg class="icon" aria-hidden="true"><use href="/assets/icons.svg#sun"></use></svg>
<span class="assistive">Color scheme: </span>
<span class="scheme-switcher-label assistive">Light</span>
</span>
<span class="scheme-switcher-option" data-cycle-value="dark" hidden>
<svg class="icon" aria-hidden="true"><use href="/assets/icons.svg#moon"></use></svg>
<span class="assistive">Color scheme: </span>
<span class="scheme-switcher-label assistive">Dark</span>
</span>
<span class="scheme-switcher-option" data-cycle-value="system">
<svg class="icon" aria-hidden="true"><use href="/assets/icons.svg#desktop"></use></svg>
<span class="assistive">Color scheme: </span>
<span class="scheme-switcher-label assistive">System</span>
</span>
</button>

Preference vs. resolved scheme. The control stores the user's preference (light, dark, or system) in localStorage under the key semetrika-color-scheme. It always writes a concrete data-color-scheme="light" or data-color-scheme="dark" to <html> - so system is resolved against the OS query at runtime and re-resolved whenever the OS preference flips. The design system only ever renders the two shipped schemes (see Color scheme); system is a preference, not a third scheme.

Avoiding a flash of the wrong scheme. Because the stylesheet loads before this component's script runs, apply the stored preference in a tiny inline <head> script before the first paint. Semetrika does not ship this snippet (a stylesheet cannot inline a head script), but this is the canonical form:

<head>
<script>
(function () {
var pref = null;
try {
pref = localStorage.getItem('semetrika-color-scheme');
} catch (e) {}
var prefersDark = false;
try {
prefersDark = !!(window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches);
} catch (e) {}
var dark = pref === 'dark' || ((!pref || pref === 'system') && prefersDark);
document.documentElement.setAttribute('data-color-scheme', dark ? 'dark' : 'light');
})();
</script>
<link rel="stylesheet" href="semetrika.css" />
</head>

React to changes. The control dispatches scheme-switcher-changed on the button; event.detail carries { preference, resolved }.

API​

Props​

PropTypeDefaultDescription
currentEnum: light, dark, systemsystemInitially shown preference before the JS reads the stored value.
has_labelsboolean-Reveals the visible text label next to each icon. Off by default (icon-only).
idstring-HTML id for the button.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Attributes​

AttributeSet byRequiredDescription
data-scheme-switcherConsumerYesMarks the scheme switcher root. Required for the JS to enhance the control.
data-cycle-currentConsumer-Owned by the cycle utility; the switcher writes the stored preference here to seed the visible option.
data-color-schemeScript-Written on the document root with the resolved scheme (light or dark) the switcher currently applies.

Events​

EventDirectionDescription
scheme-switcher-changedEmitsFired on the switcher after the color scheme changes.
cycle-changedListensHeard from the embedded cycle group; the detail value becomes the new preference.

Examples​

Switching​

Each activation advances light -> dark -> system. The resolved scheme lands on data-color-scheme, and the whole page repaints with it.

Labeled​

With has_labels, the text label sits next to each icon instead of being visually hidden.

Accessibility​

  • WCAG 2.2 AA. The control is a native <button>, so it is reachable and operable by keyboard (Enter and Space).
  • Each option carries a visually hidden Color scheme: prefix plus the option name, so the button's accessible name reads as, for example, "Color scheme: Light" and updates as it cycles - even in the default icon-only state.
  • Each option's icon is decorative (aria-hidden); the text label carries the meaning.

Dependencies​

  • cycle - drives the step-through behavior in show mode
  • icon - renders the sun / moon / desktop glyphs

Progressive enhancement​

  • No JS: the button renders whichever option the markup was authored with and is inert - reading the stored preference takes the script, and rendering a persisted option without it takes a server-side mechanism of the consumer's own. The page itself still renders in whichever scheme the head snippet applied.
  • With JS: each activation advances the preference, resolves it against the OS query, writes data-color-scheme to <html>, persists the choice, and dispatches scheme-switcher-changed.
  • How to enable: include the scheme-switcher JS. The control binds on init, so the server-rendered markup is complete before enhancement.
window.Semetrika['scheme-switcher'].init(root); // enhance controls under root
window.Semetrika['scheme-switcher'].destroy(root); // tear them down
  • Color scheme - the two-scheme token contract this control drives
  • cycle - the generic step-through utility underneath