Light, dark and system themes that are on the page before it paints, with a remembered choice, live system changes, sync across tabs and accessible controls. For vanilla JavaScript, any framework and plain HTML.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/themepnpm add @samline/themebun add @samline/themeAny modern browser; without JavaScript, your default CSS applies. On the server, createTheme is inert. No runtime dependencies.
<button type="button" data-theme-toggle>Dark mode</button>:root {
--bg: #fff;
--fg: #111;
}
[data-theme='dark'] {
--bg: #111;
--fg: #eee;
}import { createTheme } from '@samline/theme'
const theme = createTheme()
theme.set('system')
theme.subscribe(({ mode, theme }) => console.log(mode, theme))What this does:
- Reads the stored choice, or follows the system when there is none, and writes it on
<html>asdata-theme. - Sets
color-scheme, so native scrollbars and form controls follow the theme. - Makes every
data-theme-toggle,data-theme-setanddata-theme-selectcontrol work and report its state, including controls added later. - Remembers each new choice, follows the system while in
'system'mode and keeps other open tabs in sync.
A bundled module runs after the first paint. To avoid a flash, inline the snippet in <head> too:
import { themeScript } from '@samline/theme'
const head = `<script>${themeScript()}</script>`For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle in <head>, without defer, so the theme applies before the page paints. Pin the version in production.
<script src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"></script>The bundle defines window.Theme. Pass options as data-themes, data-default, data-attribute and data-storage-key on the script tag, or add data-manual and call Theme.auto(options).
The classic script, or themeScript() inlined in <head>, writes the stored theme before the first paint, so a dark page never shows light first.
Choose a theme or 'system', which follows prefers-color-scheme and updates live when the visitor changes it. Name as many themes as you need, written as data-theme or a class, with color-scheme and a theme-color per theme.
The choice is stored in localStorage and reaches every open tab. Blocked storage never throws; the theme simply is not remembered.
data-theme-set buttons get aria-pressed, radios are checked, data-theme-toggle reports dark mode and select[data-theme-select] shows the mode, all delegated, so controls added later work.
CSS transitions pause while the theme changes, so the page swaps at once. Listen with subscribe(), onChange or the themechange event.
| API | Purpose |
|---|---|
createTheme(options?) |
Apply, remember and follow the theme. Returns { mode, theme, set, toggle, subscribe, destroy }. |
themeScript(options?) |
Inline <head> snippet that applies the stored theme before the first paint. |
data-theme-set, data-theme-toggle, data-theme-select |
Controls handled without code. |
ThemeOptions |
Themes, default mode, attribute, target, theme color, storage and controls. |
themechange |
Event with { mode, theme } on every change. |
| Entrypoint | When to use |
|---|---|
@samline/theme |
ESM or CommonJS, every export. |
@samline/theme/vanilla |
createTheme as the default export. |
@samline/theme/browser |
Classic script for <head> that defines window.Theme. |
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files.
| Guide | What it covers |
|---|---|
| Installation | npm, CDN and the first toggle. |
| API reference | createTheme, themeScript, the controller and window.Theme. |
| Options | Options, controls and script attributes. |
| Layouts | CSS, custom themes, server rendering, widgets and transitions. |
| Frameworks | React, Vue, Svelte, Astro and Next.js. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
The Theme skill teaches verified package integration. Its maintained repository source and website download are the same file. Verify the installed package version before applying its guidance.
Download SKILL.md into a theme/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/theme
curl --fail --location https://samline.github.io/theme/skills/theme/SKILL.md \
--output .agents/skills/theme/SKILL.mdKeep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.