Skip to main content
xtylext xtyle
xriptxr

Scheme Toggle
Info:Controls
0

A sun/moon control that flips the active light/dark scheme.
theme dark mode light mode scheme toggle sun moon appearance reverse

Live demo

live · @xtyle/astro

SchemeToggle

The control

It's an icon-only <xtyle-button>. Click it: standalone, it flips :root[data-scheme] for the whole page and persists the choice. The glyph shows the mode you'd switch to — a sun while dark, a moon while light.

Custom glyphs

light-icon and dark-icon take any named xtyle icon — a plain glyph, or a full grammar-built one.

Reversed, and every button variant

reverse shows the mode you're in instead of the one you'd switch to. And because it composes the button, variant and size pass straight through. variant="link" drops the chrome entirely so the glyph owns the box, which is what a toolbar icon wants; iconSize then sizes the glyph on its own.

Scheme Toggle is the dark/light switch, and it is an icon-only <xtyle-button> — it composes the button rather than reinventing a control, so it inherits its variants, sizes, focus ring, hover, and mods for free. Inside an <xtyle-theme-scope> it drives the scope, which re-derives the active theme through the engine's inversion so every surface lands where the algorithm places it for the opposite mode.

Standalone, with no scope in sight, it flips :root[data-scheme], persists the choice to localStorage (key storage-key, default xtyle.scheme), and fires an xtyle:scheme-change event. The glyph follows the convention of showing the mode you'd switch to — a sun while dark, a moon while light. light-icon and dark-icon swap either glyph for any named xtyle icon, and reverse flips the convention to show the mode you're currently in (for the contrarians).

When to use

How this component composes with the rest of the set.

Drop it bare into any page for a working dark/light switch that persists across reloads and drives the site's inverted stylesheet.
Wrap it (and a <xtyle-theme-picker>) in a <xtyle-theme-scope> when the app derives themes live, so the toggle re-derives the active theme rather than swapping a prebuilt stylesheet.
It composes <xtyle-button>, so variant and size reach straight through to the button, and a Button mod restyles the toggle with it.
Swap the glyphs with light-icon / dark-icon for any named xtyle icon, and listen for xtyle:scheme-change to mirror the choice elsewhere when running standalone.

Props

8 props, straight from the manifest.

PropTypeDefaultBindingsDescription
scheme "light" | "dark"
light dark
—
html svelte astro
Pins the shown scheme. Omit to track the scope (when scoped) or `:root[data-scheme]` (standalone, defaulting to dark).
lightIcon string —
html svelte astro
A named xtyle icon for the light face, replacing the built-in sun.
darkIcon string —
html svelte astro
A named xtyle icon for the dark face, replacing the built-in moon.
iconSize IconSize
sm md lg xl
md
html svelte astro
The glyph's size, independent of the control's. A chrome-free toolbar button often wants a large glyph in a small box, which the button's own `size` cannot express.
reverse boolean false
html svelte astro
Show the mode you're currently in rather than the one you'd switch to.
variant ButtonVariant
solid outline ghost subtle link
ghost
html svelte astro
The underlying button's variant (`ghost`, `subtle`, `outline`, `solid`, `link`).
size Size
sm md lg
—
html svelte astro
The underlying button's size (`sm`, `md`, `lg`).
label string Toggle light and dark mode
html svelte astro
Accessible name for the button, used as its `aria-label`.

Appearance

States

dark

 .xtyle-scheme-toggle--dark

The scheme is dark; the light-face glyph shows (or the dark one under reverse).

light

 .xtyle-scheme-toggle--light

The scheme is light; the dark-face glyph shows (or the light one under reverse).

reverse

 .xtyle-scheme-toggle--reverse

The display is flipped to show the current mode rather than the switch-to mode.

Anatomy

The named parts that make up the component, with their selectors.

control

 .xtyle-scheme-toggle > xtyle-button

The composed icon-only <xtyle-button> that flips the scheme on click.

light

 .xtyle-scheme-toggle__light

The light-face glyph (default a sun), shown while dark unless reverse is set.

dark

 .xtyle-scheme-toggle__dark

The dark-face glyph (default a moon), shown while light unless reverse is set.

Tokens & coverage

What the component consumes, checked live against what the algorithm produces.

Success:fully covered 0/0 consumed tokens produced default register: 310 tokens

Live coverage check against the xtyle-default register (derive(xtyleDefault, { anchors }) → coverComponent(manifest, register)). Every token this component consumes must be a key the algorithm produces.

Accessibility
Composes an icon-only <xtyle-button> with an aria-label, so it is a real, reachable, announced button.
Only one glyph is shown at a time, and both are decorative (aria-hidden); the button's label carries the meaning, not the icon.
Focus, hover, and the focus ring come from the composed button, consistent with every other control.

Code

Standalone, custom icons, and reversed

A bare toggle that flips the document scheme, one with custom glyphs and a reversed display, and one inside a theme scope.

 
<!-- Standalone: flips :root[data-scheme] and persists the choice -->
<xtyle-scheme-toggle></xtyle-scheme-toggle>

<!-- Custom glyphs (any named xtyle icon) and a reversed display -->
<xtyle-scheme-toggle
	light-icon="light-theme--sun-c3--circle-s65-ko--circle-s55-c3---ps-skittles"
	dark-icon="dark-theme--circle-c3--circle-x20-y-10-s80-ko---ps-skittles"
	reverse
></xtyle-scheme-toggle>

<!-- A toolbar icon: no chrome of its own, so the glyph owns the box -->
<xtyle-scheme-toggle variant="link" icon-size="lg"></xtyle-scheme-toggle>

<!-- Inside a theme scope: drives the scope, which re-derives the active theme -->
<xtyle-theme-scope>
	<xtyle-scheme-toggle variant="subtle" label="Switch theme mode"></xtyle-scheme-toggle>
</xtyle-theme-scope>