ComponentsNavigation

Mode toggle

A light / dark (and optionally system) switch. It toggles the kit's .dark class on the document or any element, can remember the choice in localStorage, follows the OS live in system mode, and ships a head script so a stored choice never flashes on reload.

Toggle button (aria-pressed) / radio group components/mode-toggle.tsxtheme · material · accent · density · font
Field notes

Installation

$ pnpm add @vamos-ui/react

The whole kit as one package — get updates by bumping the version. Add the styles to globals.css: @import "@vamos-ui/react/styles.css";

Usage

import { ModeToggle, modeToggleScript } from "@vamos-ui/react";

// In <head>, before the page paints:
<script dangerouslySetInnerHTML={{ __html: modeToggleScript("site:mode") }} />

<ModeToggle storageKey="site:mode" />
<ModeToggle variant="segmented" modes={["light", "dark", "system"]} showLabel />

Nothing is written to the target until the stored mode is read, so a class set by the head script is never flipped off during hydration.

Storage failures (private mode) are ignored; the choice then lasts for the page.

Examples

Light, dark and system

variant="segmented" shows every mode; system follows prefers-color-scheme as it changes.

Appearance

Controlled (SiteShell, ThemeScope)

target={null} leaves the DOM alone; pass the mode to SiteShell's theme or a ThemeScope.

Reader view

API

ModeToggle

PropTypeDefault
value / defaultValue
Controlled or initial mode. Uncontrolled default: the stored choice, else what the target already shows.
"light" | "dark" | "system"—
onValueChange
The chosen mode and what it resolves to.
(mode, resolved: "light" | "dark") => void—
modes
Modes offered, in order.
ColorMode[]["light", "dark"]
variant
One icon button (dark-mode toggle with two modes, cycling with three) or one option per mode.
"button" | "segmented""button"
target
Where the .dark class goes; null only reports.
HTMLElement | (() => HTMLElement | null) | nulldocument.documentElement
storageKey
Remember the choice in localStorage.
string—
showLabel
Show the mode name next to the icon.
booleanfalse
size
Control size.
"xs" | "sm" | "md""sm"
labels
Dictionary namespace "modeToggle": label, light, dark, system, darkMode, current.
Partial<ModeToggleLabels>—

modeToggleScript(storageKey, fallback?)

PropTypeDefault
returns
Inline script for <head> that applies the stored mode before first paint. fallback defaults to "system".
string—
Previous
Menubar
Next
Motion