- Docs
- Getting started
Getting started
Install @samline/theme with a package manager or a script tag, apply the theme before the first paint and add your first dark mode toggle.
Install @samline/theme, then follow the Package / ESM or the HTML / CDN path to the first toggle. Both use the same API.
Requirements
- Any modern browser. Without JavaScript, your default CSS applies.
- On the server,
createThemereturns an inert controller with the default mode, andthemeScriptreturns a string. - No runtime dependencies.
Install
npm
npm install @samline/themepnpm
pnpm add @samline/themeyarn
yarn add @samline/themebun
bun add @samline/themeHTML / CDN
<script src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"></script>Package / ESM
import { createTheme } from '@samline/theme'
const theme = createTheme()
theme.toggle()
A bundled module runs after the page paints, so on its own it can flash. Pair it with the inline snippet in <head>, which applies the stored theme first:
import { themeScript } from '@samline/theme'
const head = `<script>${themeScript()}</script>`
Pass the same themes, defaultMode, attribute and storageKey to both. Available as ESM and CommonJS (require('@samline/theme')). There is no stylesheet: style [data-theme] in your own CSS.
HTML / CDN
For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle in <head>, without defer or async, so the theme is written before the page paints. Pin the version in production.
<head>
<script src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"></script>
</head>
<body>
<button type="button" data-theme-toggle>Dark mode</button>
</body>
Options go on the script tag:
<script
src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"
data-themes="light dark sepia"
data-default="light"
data-attribute="class"
></script>
For options a tag cannot hold, such as themeColor, add data-manual and start it yourself right after, still in <head>:
<script
src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"
data-manual
></script>
<script>
Theme.auto({ themeColor: { light: '#ffffff', dark: '#111111' } })
</script>
Working starter files
A complete page you can save and open: the live preview runs the real package, and its files load the published browser bundle.
A data-theme-toggle button switches between light and dark from the theme in effect and reports its state with aria-pressed. The choice is remembered.
This box remembers its own theme. Reload the page: it stays.
Explore the code
HTML / CDN
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>One button for dark mode</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<button type="button" class="toggle" data-theme-toggle>
<svg
width="1em"
height="1em"
viewBox="0 0 24 24"
aria-hidden="true"
style="vertical-align: -0.125em"
>
<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2" />
<path d="M12 3a9 9 0 0 1 0 18z" fill="currentColor" />
</svg>
Dark mode
</button>
<div class="card">
<h1>Hello</h1>
<p>
Reload the page: your choice stays. Change your system theme: nothing moves until you go
back to it.
</p>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"></script>
<script src="./main.js" defer></script>
</body>
</html>
CSS
:root {
--bg: #ffffff;
--fg: #18181b;
--card: #f4f4f5;
--accent: #0e7490;
}
[data-theme='dark'] {
--bg: #18181b;
--fg: #f4f4f5;
--card: #27272a;
--accent: #22d3ee;
}
body {
margin: 0;
min-height: 100vh;
background: var(--bg);
color: var(--fg);
font-family: system-ui, sans-serif;
}
main {
display: grid;
gap: 1rem;
max-width: 32rem;
margin: 0 auto;
padding: 2rem 1rem;
}
.card {
padding: 1rem;
border-radius: 0.75rem;
background: var(--card);
}
.toggle {
justify-self: start;
padding: 0.5rem 1rem;
border: 1px solid currentColor;
border-radius: 999px;
background: none;
color: inherit;
font: inherit;
cursor: pointer;
}
.toggle[aria-pressed='true'] {
background: var(--accent);
border-color: var(--accent);
color: var(--bg);
}
JavaScript
// Nothing to call: the script applies the theme and handles [data-theme-toggle].
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>One button for dark mode</title>
<style>
:root {
--bg: #ffffff;
--fg: #18181b;
--card: #f4f4f5;
--accent: #0e7490;
}
[data-theme='dark'] {
--bg: #18181b;
--fg: #f4f4f5;
--card: #27272a;
--accent: #22d3ee;
}
body {
margin: 0;
min-height: 100vh;
background: var(--bg);
color: var(--fg);
font-family: system-ui, sans-serif;
}
main {
display: grid;
gap: 1rem;
max-width: 32rem;
margin: 0 auto;
padding: 2rem 1rem;
}
.card {
padding: 1rem;
border-radius: 0.75rem;
background: var(--card);
}
.toggle {
justify-self: start;
padding: 0.5rem 1rem;
border: 1px solid currentColor;
border-radius: 999px;
background: none;
color: inherit;
font: inherit;
cursor: pointer;
}
.toggle[aria-pressed='true'] {
background: var(--accent);
border-color: var(--accent);
color: var(--bg);
}
</style>
</head>
<body>
<main>
<button type="button" class="toggle" data-theme-toggle>
<svg
width="1em"
height="1em"
viewBox="0 0 24 24"
aria-hidden="true"
style="vertical-align: -0.125em"
>
<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2" />
<path d="M12 3a9 9 0 0 1 0 18z" fill="currentColor" />
</svg>
Dark mode
</button>
<div class="card">
<h1>Hello</h1>
<p>
Reload the page: your choice stays. Change your system theme: nothing moves until you go
back to it.
</p>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/theme@1.1.0/dist/browser/theme.global.js"></script>
<script>
// Nothing to call: the script applies the theme and handles [data-theme-toggle].
</script>
</body>
</html>
Package / ESM
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>One button for dark mode</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<button type="button" class="toggle" data-theme-toggle>
<svg
width="1em"
height="1em"
viewBox="0 0 24 24"
aria-hidden="true"
style="vertical-align: -0.125em"
>
<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2" />
<path d="M12 3a9 9 0 0 1 0 18z" fill="currentColor" />
</svg>
Dark mode
</button>
<div class="card">
<h1>Hello</h1>
<p>
Reload the page: your choice stays. Change your system theme: nothing moves until you go
back to it.
</p>
</div>
</main>
<script type="module" src="./main.js"></script>
</body>
</html>
CSS
:root {
--bg: #ffffff;
--fg: #18181b;
--card: #f4f4f5;
--accent: #0e7490;
}
[data-theme='dark'] {
--bg: #18181b;
--fg: #f4f4f5;
--card: #27272a;
--accent: #22d3ee;
}
body {
margin: 0;
min-height: 100vh;
background: var(--bg);
color: var(--fg);
font-family: system-ui, sans-serif;
}
main {
display: grid;
gap: 1rem;
max-width: 32rem;
margin: 0 auto;
padding: 2rem 1rem;
}
.card {
padding: 1rem;
border-radius: 0.75rem;
background: var(--card);
}
.toggle {
justify-self: start;
padding: 0.5rem 1rem;
border: 1px solid currentColor;
border-radius: 999px;
background: none;
color: inherit;
font: inherit;
cursor: pointer;
}
.toggle[aria-pressed='true'] {
background: var(--accent);
border-color: var(--accent);
color: var(--bg);
}
JavaScript
import { createTheme } from '@samline/theme'
createTheme()
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>One button for dark mode</title>
<style>
:root {
--bg: #ffffff;
--fg: #18181b;
--card: #f4f4f5;
--accent: #0e7490;
}
[data-theme='dark'] {
--bg: #18181b;
--fg: #f4f4f5;
--card: #27272a;
--accent: #22d3ee;
}
body {
margin: 0;
min-height: 100vh;
background: var(--bg);
color: var(--fg);
font-family: system-ui, sans-serif;
}
main {
display: grid;
gap: 1rem;
max-width: 32rem;
margin: 0 auto;
padding: 2rem 1rem;
}
.card {
padding: 1rem;
border-radius: 0.75rem;
background: var(--card);
}
.toggle {
justify-self: start;
padding: 0.5rem 1rem;
border: 1px solid currentColor;
border-radius: 999px;
background: none;
color: inherit;
font: inherit;
cursor: pointer;
}
.toggle[aria-pressed='true'] {
background: var(--accent);
border-color: var(--accent);
color: var(--bg);
}
</style>
</head>
<body>
<main>
<button type="button" class="toggle" data-theme-toggle>
<svg
width="1em"
height="1em"
viewBox="0 0 24 24"
aria-hidden="true"
style="vertical-align: -0.125em"
>
<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2" />
<path d="M12 3a9 9 0 0 1 0 18z" fill="currentColor" />
</svg>
Dark mode
</button>
<div class="card">
<h1>Hello</h1>
<p>
Reload the page: your choice stays. Change your system theme: nothing moves until you go
back to it.
</p>
</div>
</main>
<script type="module">
import { createTheme } from '@samline/theme'
createTheme()
</script>
</body>
</html>
Next steps
Live previews with the complete, copyable source of each one.
API referenceSignatures and behavior of createTheme, themeScript, the controller and window.Theme.
Options, controls and script attributes.
Styling and renderingCSS, custom themes, server rendering, widgets and transitions.
Accessibility and contrastFocus, reduced motion and what your page provides.
Framework integrationsReact, Vue, Svelte, Astro and Next.js.