Dark Mode Implementation Cheat Sheet

Covers CSS custom-property theming, prefers-color-scheme, flash-of-wrong-theme prevention, persisted toggle logic, and Tailwind's class-based dark mode setup.

2 PagesIntermediateMar 2, 2026

Theming Strategies

The building blocks behind most dark mode implementations.

data-theme attribute- Set via JS on <html>, paired with CSS attribute selectors for explicit, user-controlled themes
prefers-color-scheme- Media query reflecting the OS/browser-level light or dark preference
color-scheme (CSS property)- Tells the browser to render native form controls and scrollbars to match your theme
CSS custom properties- Centralize color tokens as variables so switching themes only reassigns values, not selectors
FOUC- Flash of unstyled/incorrect content, avoided by reading the saved theme before first paint
localStorage persistence- Remembers an explicit user choice across visits, overriding the OS default

CSS Variables & Media Query

Theme tokens with an OS-preference fallback.

css

:root {  --bg: #ffffff;  --text: #1a1a1a;  --accent: #2563eb;  color-scheme: light; /* native controls/scrollbars render light */}[data-theme="dark"] {  --bg: #0f172a;  --text: #e2e8f0;  --accent: #60a5fa;  color-scheme: dark;}/* Fall back to OS preference only when no explicit choice is set */@media (prefers-color-scheme: dark) {  :root:not([data-theme="light"]) {    --bg: #0f172a;    --text: #e2e8f0;  }}body {  background: var(--bg);  color: var(--text);  transition: background 0.2s ease, color 0.2s ease;}

Prevent Flash of Wrong Theme

Blocking inline script that runs before the CSS paints.

html

<!-- In <head>, before stylesheets --><script>  (function () {    var saved = localStorage.getItem('theme');    var systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;    document.documentElement.setAttribute('data-theme', saved || (systemDark ? 'dark' : 'light'));  })();</script>

Toggle & Persist Theme

User-triggered switch that also reacts to OS changes.

javascript

function setTheme(theme) {  document.documentElement.setAttribute('data-theme', theme);  localStorage.setItem('theme', theme);}document.querySelector('#theme-toggle').addEventListener('click', () => {  const current = document.documentElement.getAttribute('data-theme');  setTheme(current === 'dark' ? 'light' : 'dark');});// Follow OS changes only if the user hasn't made an explicit choicewindow.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {  if (!localStorage.getItem('theme')) {    setTheme(e.matches ? 'dark' : 'light');  }});

Tailwind Dark Mode

Class-based strategy for full manual control.

javascript

// tailwind.config.jsmodule.exports = {  darkMode: 'class', // toggled via a .dark class on <html>, instead of 'media'  theme: { extend: {} },};// Usage in markup:// <div class="bg-white dark:bg-slate-900 text-black dark:text-slate-100">

Pro Tip

Set the color-scheme CSS property alongside your custom theme — it tells the browser to render native widgets like scrollbars, checkboxes, and date pickers in the matching light or dark style, so your theme doesn't feel broken at the edges.

Was this cheat sheet helpful?

Internationalization (i18n) Cheat Sheet

Vue Router Cheat Sheet