Dark mode, done once.

Theme
Themes that never flash.

The stored theme is on the page before it paints, follows the system while visitors want it to, and stays in sync across tabs and controls.
Install it, try the live preview, then read the full reference.

npm install @samline/theme

About 1.8 KB gzipZero dependenciesMIT licensed

Theme previewLive preview
AcmePricing

Pick a theme, then reload

The choice is remembered. On System, changing your operating system's appearance updates this box live.

ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.

JavaScript TypeScript React Vue Svelte Shopify WordPress
01 / More than a class toggle

The switch is easy.
The rest is not.

No flash on load

A classic script in the head, or a small inline snippet for SSR, writes the theme before the first paint.

Accessible controls

Buttons get aria-pressed, radios are checked and selects show the mode, with no extra code.

Follows the system

In system mode, a change in the operating system appearance updates the page at once.

Every tab agrees

A choice made in one tab reaches the others, and broken storage never throws.

Your themes, your CSS

Any number of named themes, as data-theme or a class, with color-scheme and theme-color set for you.

No animated switch

Transitions pause while the theme changes, so the page swaps at once instead of fading every element.

02 / Fit it into your stack

One script tag. Or one function.

Your CSS stays in charge: the package only writes the theme name.

Package

@samline/theme

createTheme and themeScript as ESM or CommonJS.

Controller

createTheme(options)

mode, theme, set, toggle, subscribe and destroy.

SSR head

themeScript(options)

An inline snippet for your server-rendered head.

HTML / CDN

window.Theme

A classic script for the head that applies at once.

Controls

data-theme-*

Buttons, radios, toggles and selects, without code.

Styling

Your CSS variables

Style [data-theme] or a class; no stylesheet ships.

03 / Install and switch

One button. One call.

Add a remembered dark mode to any page, without a flash.

Read the installation guide
1

Install

npm

Terminal
npm install @samline/theme

pnpm

Terminal
pnpm add @samline/theme

yarn

Terminal
yarn add @samline/theme

bun

Terminal
bun add @samline/theme

HTML / CDN

Terminal
<script src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"></script>
2

Add a control

A data-theme-toggle button switches dark mode and reports it with aria-pressed. Inline themeScript() in the head too, so the theme is on the page before it paints.

index.html
<button type="button" data-theme-toggle>Dark mode</button>
3

Start it

main.js
import { createTheme } from '@samline/theme'

// Style [data-theme='dark'] in your CSS.
createTheme()
Copy complete working files

Continue with every option, custom themes and server rendering.

Explore the options
04 / Beyond light and dark

One controller.
Every kind of theme.

Three common jobs, without touching storage or media queries yourself.

data-theme-set

Light, dark or system

A three-way picker in plain HTML.

Read the options
index.html
<button type="button" data-theme-set="light">Light</button>
<button type="button" data-theme-set="system">System</button>
<button type="button" data-theme-set="dark">Dark</button>
themeScript

Server-rendered pages

Inline the snippet in your head.

Read the API
head.js
import { themeScript } from '@samline/theme'

const head = `<script>${themeScript()}</script>`
subscribe

React to changes

Repaint a chart when the theme changes.

Read the API
main.js
import { createTheme } from '@samline/theme'

const theme = createTheme()
theme.subscribe(({ theme }) => chart.setTheme(theme))
Explore working examples
05 / Before you build

A few details. Clearly answered.

Why does the page flash light before going dark?
The theme was applied after the page painted. Load the browser script in the head without defer or async, or inline themeScript() there, so the theme is written first.
Does it work without a bundler?
Yes. Load dist/browser/theme.global.js in the head; it applies the theme and handles data-theme-* controls. Options go on the script tag, or add data-manual and call Theme.auto(). Pin the version in production.
What does system mode do?
It follows prefers-color-scheme and updates live when the visitor changes it. Choosing light or dark stops following it until system is chosen again.
Can I have more than two themes?
Yes. Pass any theme names; each can have a theme-color for the browser UI. color-scheme is only set for light and dark, and the toggle always switches between light and dark.
Can I theme only part of a page?
Yes. Pass target to write the theme on a widget instead of <html>, scope to limit which controls it listens to, and its own storageKey so it does not share the page choice.
What if storage is blocked?
The theme still works for the page; it is just not remembered. Set storageKey: false to never store it.
What happens without JavaScript?
Your default CSS applies. Style the system preference with a prefers-color-scheme media query if you want dark without JavaScript too.
Do controls added later work?
Yes. Clicks and changes are delegated, so controls added at any time work, and every control is synced again on each change.
Themes with care

Every visit, the right theme.

Try the examples or follow the first steps.

Guides, the complete API and release notes, in one place.

Read the documentation