Theme Switch
Freev1.0.0One button that flips between light and dark mode, with a sweep across the page.
Build for your project
Code/install build
Usage
Import it and pass your content. The props that matter most are listed next.
Example
"use client";
import { NotchsetThemeScript, ThemeSwitch } from "@/components/ui/notchset/theme-switch";
/** In your root layout's <head>: applies the saved (or system) theme before first paint. */
export function ThemeHead() {
return <NotchsetThemeScript />;
}
/**
* On its own the switch reads the page's theme, toggles the dark class on <html> and saves the choice,
* so a restored dark theme is never overwritten on mount. With next-themes, pass resolvedTheme and
* setTheme as theme and onThemeChange instead.
*/
export function ThemeToggle() {
return <ThemeSwitch />;
}Props
theme / onThemeChange–"light" | "dark" / (theme) => voidControlled, e.g. with next-themes' resolvedTheme and setTheme.
defaultTheme–"light" | "dark"Uncontrolled start. Without either, it reads and toggles the dark class on <html> and saves the choice under localStorage "theme".
label–stringThe key's label. Default "SWITCH THEME".
iconOnly–booleanA 40×40 key.
sweep–booleanThe View Transitions sweep. Default true; instant without support or under reduced motion.
labels–{ toDark?, toLight? }The accessible names.
Anatomy
- View Transitions for the sweep, with an instant fallback.
- Works with next-themes or on its own (the dark class, localStorage).
- One file serves both builds.
ThemeSwitchdata-slot="theme-switch"The key (className and ref land here).
Platedata-slot="theme-switch-plated"The key's plate.
Source
components/ui/notchset/theme-switch.tsx
Loading the code
Build for your project
Code/install build
Installation
Base UI
pnpm dlx shadcn@latest add https://notchset.dev/r/theme-switch.jsonRadix
pnpm dlx shadcn@latest add https://notchset.dev/r/radix-nova/theme-switch.jsonFree, no account or key. Use the command for your project's primitives: a radix-*, new-york or default style in components.json is Radix, a base-* style is Base UI. With the @notchset registry added, @notchset/<name> picks for you.
Install by hand
- 1. No extra packages: React and Tailwind CSS v4 are enough.
- 2. Copy the files to these paths (the source, or save them all as a .zip)
- components/ui/notchset/theme-switch.tsx
- lib/beautiful-ui/notchset/instrument.tsx
- lib/beautiful-ui/notchset/root.ts
- 3. No stylesheet needed.
- 4. Install what it builds on first: shadcn's cn helper (lib/utils.ts, from npx shadcn init), the theme foundation (its tokens and base styles)
Styles didn't apply?
The CLI adds the styles to the CSS file named in components.json (tailwind.css). Check that it points at your global stylesheet, that the project uses Tailwind CSS v4, and that the file is imported in your root layout. Installed by hand: paste styles.css into that file.
For coding agents
Give your coding assistant the Markdown guide instead of screenshots.
Use it for
- The light / dark control in a header or settings
Use something else when
- Three-way light / dark / system choices: use a Select or Button Group
Mistakes to avoid
- With next-themes, control it: pass theme and onThemeChange
- Add the Notchset foundation once (installed with it): the sweep's CSS lives there
Agents find it by
- theme switch, dark mode toggle, light dark, color mode, theme toggle, view transition, Notchset
Where agents read it
- Guide for this component: https://notchset.dev/md/theme-switch.md
- Every component, for tools without MCP: /llms.txt
- MCP server:
https://notchset.dev/api/mcp(setup)
Behaviour
Keyboard
- Enter / Space
- Switch theme
Accessibility
- The name says what pressing does: Switch to dark theme / Switch to light theme
- Reduced motion swaps instantly, with no sweep
- The glyph is decorative (aria-hidden)
Motion
- To dark
- Rays scale to .3 and fade (22ms apart); the core grows to r 7.5; the mask slides in to cut the crescent; the glyph tilts to −28°
- To light
- The mask slides out, the core shrinks, the rays spring back with an overshoot, 28ms apart
- Sweep
- The new theme is revealed by clip-path from the side of the change over 580ms cubic-bezier(.7,0,.25,1), behind a 1px signal line that fades over the last 100ms
Responsive
- A fixed three-cell switch; it never wraps.
- 44px cells on touch screens.
Performance
- The sweep uses the View Transitions API when the browser has it and swaps instantly when it doesn't.
- The theme script runs before paint, so there is no flash of the wrong theme.
Changelog
v1.0.0 · 2026-10-02
First release
