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-schemeand 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,darkandsystemare the whole set, andsystemis a preference rather than a third scheme - Write
data-color-schemeanywhere 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
| Prop | Type | Default | Description |
|---|---|---|---|
current | Enum: light, dark, system | system | Initially shown preference before the JS reads the stored value. |
has_labels | boolean | - | Reveals the visible text label next to each icon. Off by default (icon-only). |
id | string | - | HTML id for the button. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-scheme-switcher | Consumer | Yes | Marks the scheme switcher root. Required for the JS to enhance the control. |
data-cycle-current | Consumer | - | Owned by the cycle utility; the switcher writes the stored preference here to seed the visible option. |
data-color-scheme | Script | - | Written on the document root with the resolved scheme (light or dark) the switcher currently applies. |
Events
| Event | Direction | Description |
|---|---|---|
scheme-switcher-changed | Emits | Fired on the switcher after the color scheme changes. |
cycle-changed | Listens | Heard 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
showmode - 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-schemeto<html>, persists the choice, and dispatchesscheme-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
Related
- Color scheme - the two-scheme token contract this control drives
- cycle - the generic step-through utility underneath