A Practical CSS Variable Setup for Light/Dark Mode Without Theme Flash
DEV Community

A Practical CSS Variable Setup for Light/Dark Mode Without Theme Flash

Dark mode is easy to start. It is harder to ship cleanly. Most implementations need to handle:

  • light mode
  • dark mode
  • system preference
  • stored user preference
  • a toggle button
  • no flash of the wrong theme on page load

That last one is the annoying part. You save the user's choice in localStorage, but your app JavaScript usually runs after the browser has already started parsing HTML and CSS. So the page may briefly render in the wrong theme before JavaScript applies the saved preference.

This article shows a practical setup using:

  • CSS variables
  • data-theme on <html>
  • prefers-color-scheme
  • localStorage
  • a tiny inline script in <head>

No framework required.

The goal

I want components to use semantic variables like this:

body {
  background: var(--color-background);
  color: var(--color-text);
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

The component should not care whether the app is currently in light mode or dark mode. Only the variable values should change.

Step 1: define light mode variables

Start with light mode as the default.

:root, :root[data-theme="light"] {
  color-scheme: light;
  --color-background: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #64748b;
  --color-border: #e2e8f0;
  --color-primary: #2563eb;
  --color-on-primary: #ffffff;
}

This means that if nothing else happens, the site renders in light mode. That is a safe default. Notice that I also include :root[data-theme="light"]. This makes the explicit light mode clear and predictable.

Step 2: add explicit dark mode

Now add dark mode using data-theme="dark" on the root element.

:root[data-theme="dark"] {
  color-scheme: dark;
  --color-background: #020617;
  --color-surface: #0f172a;
  --color-text: #f8fafc;
  --color-muted: #94a3b8;
  --color-border: #1e293b;
  --color-primary: #60a5fa;
  --color-on-primary: #020617;
}

When this attribute exists: <html data-theme="dark">, the dark variables override the light variables. Your component CSS does not change.

Step 3: support system preference

Some users prefer dark mode at the OS level. You can respect that with prefers-color-scheme.

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;
    --color-background: #020617;
    --color-surface: #0f172a;
    --color-text: #f8fafc;
    --color-muted: #94a3b8;
    --color-border: #1e293b;
    --color-primary: #60a5fa;
    --color-on-primary: #020617;
  }
}

The important part is this selector: :root:not([data-theme="light"]). It means: Use system dark mode unless the user explicitly selected light mode.

So the behavior becomes:

Situation Result
No saved choice + OS light light
No saved choice + OS dark dark
Saved light light
Saved dark dark

Step 4: Prevent the wrong theme from flashing

This is the critical piece. Add a small inline script in <head> before your theme CSS.

<script>
(function () {
  try {
    var storedTheme = localStorage.getItem('theme');
    if (storedTheme === 'light' || storedTheme === 'dark') {
      document.documentElement.setAttribute('data-theme', storedTheme);
    }
  } catch (_) {}
})();
</script>

Do not run this script after the page loads. Avoid this:

<script defer src="/theme.js"></script>

Avoid this:

document.addEventListener('DOMContentLoaded', function () {
  // set theme here
});

The script should run immediately while the browser is still parsing the <head>. Why? Because the browser reads the document from top to bottom. If this script sets data-theme="dark" before the CSS is applied, the correct variables are active before the first paint. That prevents the wrong theme from flashing.

Recommended HTML structure

Put the inline script before the CSS.

<!doctype html>
<html lang="en">
<head>
  <script>
  (function () {
    try {
      var storedTheme = localStorage.getItem('theme');
      if (storedTheme === 'light' || storedTheme === 'dark') {
        document.documentElement.setAttribute('data-theme', storedTheme);
      }
    } catch (_) {}
  })();
  </script>
  <style>
    :root, :root[data-theme="light"] {
      color-scheme: light;
      --color-background: #ffffff;
      --color-surface: #f8fafc;
      --color-text: #0f172a;
      --color-muted: #64748b;
      --color-border: #e2e8f0;
      --color-primary: #2563eb;
      --color-on-primary: #ffffff;
    }
    :root[data-theme="dark"] {
      color-scheme: dark;
      --color-background: #020617;
      --color-surface: #0f172a;
      --color-text: #f8fafc;
      --color-muted: #94a3b8;
      --color-border: #1e293b;
      --color-primary: #60a5fa;
      --color-on-primary: #020617;
    }
    @media (prefers-color-scheme: dark) {
      :root:not([data-theme="light"]) {
        color-scheme: dark;
        --color-background: #020617;
        --color-surface: #0f172a;
        --color-text: #f8fafc;
        --color-muted: #94a3b8;
        --color-border: #1e293b;
        --color-primary: #60a5fa;
        --color-on-primary: #020617;
      }
    }
  </style>
</head>
<body>
  <button id="theme-toggle" type="button">Toggle theme</button>
</body>
</html>

The order matters:

  1. Inline script reads saved preference
  2. Script sets data-theme on <html>
  3. CSS variables are applied
  4. The browser paints the page

If the order is reversed, the wrong theme can appear briefly.

Step 5: Add the toggle function

Now add a simple toggle.

function toggleTheme() {
  var html = document.documentElement;
  var currentTheme = html.getAttribute('data-theme');
  var nextTheme = currentTheme === 'dark' ? 'light' : 'dark';
  html.setAttribute('data-theme', nextTheme);
  localStorage.setItem('theme', nextTheme);
}

document.getElementById('theme-toggle')?.addEventListener('click', toggleTheme);

Now, clicking the button switches between <html data-theme="light"> and <html data-theme="dark">. The variables update instantly. No component-specific class changes are needed.

Step 6: Add system mode

A good theme switcher often has three options: light, dark, system.

For system mode, remove the attribute and clear localStorage.

function resetToSystemTheme() {
  document.documentElement.removeAttribute('data-theme');
  localStorage.removeItem('theme');
}

Now the media query controls the theme again:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* dark variables */
  }
}

This gives users a proper system preference option.

Why color-scheme matters

This line is easy to forget:

color-scheme: light;

and:

color-scheme: dark;

It tells the browser which color scheme your page supports. That can affect built-in UI such as:

  • form controls
  • scrollbars
  • default input styling
  • browser-rendered UI pieces

So your page does not only change your custom CSS variables. Native browser UI also gets a better matching appearance.

Component CSS stays simple

Once the variables are defined, component CSS becomes boring. That is good.

body {
  margin: 0;
  background: var(--color-background);
  color: var(--color-text);
  font-family: system-ui, sans-serif;
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: 12px;
  padding: 1rem;
}

.card-muted {
  color: var(--color-muted);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
  border: 0;
  border-radius: 8px;
  padding: 0.625rem 1rem;
  cursor: pointer;
}

.button:hover {
  filter: brightness(0.95);
}

There is no separate .dark .button rule. The variables handle the mode.

Why semantic variables are better than color names

You could name your variables like this:

--blue-600: #2563eb;
--slate-950: #020617;
--white: #ffffff;

But that becomes awkward in dark mode. For example:

.button {
  background: var(--blue-600);
}

Should --blue-600 become lighter in dark mode? Should it stay the same? What happens if the primary color is no longer blue?

Semantic names are more flexible:

  • --color-background
  • --color-surface
  • --color-text
  • --color-muted
  • --color-border
  • --color-primary
  • --color-on-primary

These describe purpose, not appearance. That makes the component CSS more stable.

The limitation

This setup solves the theme switching structure. It does not solve color design for you. You still need to decide:

  • which light colors to use
  • which dark colors to use
  • whether text has enough contrast
  • what hover, pressed, focused, and disabled states should be
  • what color should go on top of primary buttons
  • how semantic colors like success, warning, danger, and info behave in both modes

For a small project, manually writing variables may be enough. For a larger system, maintaining all values by hand can become repetitive.

Optional: generating the variables

If you already have a design-token source, you can generate the CSS instead of writing it manually. The output can still use the same structure:

:root, :root[data-theme="light"] {
  --color-background: ...;
  --color-text: ...;
}

:root[data-theme="dark"] {
  --color-background: ...;
  --color-text: ...;
}

The browser does not care whether the variables were handwritten or generated. The important part is the contract:

background: var(--color-background);
color: var(--color-text);

The component uses meaning. The theme supplies values.

The bottom line

A reliable light/dark setup does not need to be complicated. The key pieces are:

  • CSS variables for tokens
  • data-theme on <html>
  • prefers-color-scheme for system fallback
  • localStorage for user preference
  • inline script in <head> to avoid theme flash

The most important rule is: Set the saved theme before the CSS is applied. After that, your components can stay clean:

background: var(--color-background);
color: var(--color-text);

The values change between light and dark mode. The component contract stays the same.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.