Guide

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, createTheme returns an inert controller with the default mode, and themeScript returns a string.
  • No runtime dependencies.

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>

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.

Dark mode toggleLive preview

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

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

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

main.js
// Nothing to call: the script applies the theme and handles [data-theme-toggle].

Complete file

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

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

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

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

createTheme()

Complete file

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