Skip to content
samlinePublic

About

Light, dark and system themes without a flash: stored choice, system preference, other tabs, color-scheme and accessible toggle, button, radio and select controls, for vanilla JavaScript, any framework and plain HTML.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

27 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@samline/theme

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

Table of contents

Installation

npm install @samline/theme
pnpm add @samline/theme
bun add @samline/theme

Any modern browser; without JavaScript, your default CSS applies. On the server, createTheme is inert. No runtime dependencies.

Quick start

<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> as data-theme.
  • Sets color-scheme, so native scrollbars and form controls follow the theme.
  • Makes every data-theme-toggle, data-theme-set and data-theme-select control 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>`

HTML / CDN

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).

Capabilities

No flash on load

The classic script, or themeScript() inlined in <head>, writes the stored theme before the first paint, so a dark page never shows light first.

Light, dark, system and your own themes

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.

Remembered and in sync

The choice is stored in localStorage and reaches every open tab. Blocked storage never throws; the theme simply is not remembered.

Accessible controls without code

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.

A clean switch

CSS transitions pause while the theme changes, so the page swaps at once. Listen with subscribe(), onChange or the themechange event.

API at a glance

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.

Entrypoints

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.

Documentation

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.

Changelog

Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.

AI agent skill

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.md

Keep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.

License

MIT — LICENSE.md.

About

Light, dark and system themes without a flash: stored choice, system preference, other tabs, color-scheme and accessible toggle, button, radio and select controls, for vanilla JavaScript, any framework and plain HTML.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages