On this page

Dark Mode (prefers-color-scheme, light-dark())

Badar KhalilUpdated September 30, 2026 9 min read

CSS Dark Mode: prefers-color-scheme and light-dark()

Focus keyword: CSS dark mode. Dark mode is now an expected feature. Many users set their operating system to dark, and they expect your website to follow. In this lesson you will learn the prefers-color-scheme media query, the color-scheme property, the light-dark() function, how to build a manual theme toggle with three states, how to avoid the flash of the wrong theme, and how to design a dark palette that is readable and accessible.

CSS dark mode, prefers-color-scheme, light-dark() function, color-scheme property, meta color-scheme, dark mode toggle, dark mode localStorage, flash of incorrect theme, theme-color meta tag, dark mode CSS variables, data-theme attribute, system light dark theme, dark mode images, dark mode contrast, WCAG contrast ratio, color-mix, accent-color, prefers-contrast, forced-colors, prefers-reduced-motion, dark mode design tips.

1. How Dark Mode Works

The operating system or browser exposes the user's preference. CSS reads it with a media query, and the browser can also adapt built-in controls such as form fields and scrollbars. A good implementation has three parts: a default that follows the system, optional manual override by the user, and a palette designed for both themes.

2. The prefers-color-scheme Media Query

@media (prefers-color-scheme: dark) { ... } matches when the user prefers a dark theme. The other value is light. The recommended pattern is to define your colors as CSS variables on :root for light and redefine the same variables inside the dark media query. Components then use the variables and need no dark-specific rules.

3. The color-scheme Property and Meta Tag

The property color-scheme: light dark on :root tells the browser that your page supports both schemes. The browser then switches default colors for the canvas, text, form controls, scrollbars and the focus ring. You can also add the HTML tag <meta name='color-scheme' content='light dark'> in the head so the very first paint has the right background and avoids a white flash. Use color-scheme: only light only when you truly do not want the browser to adapt.

4. The light-dark() Function

light-dark(lightValue, darkValue) returns the first color in a light scheme and the second in a dark scheme. Example: background: light-dark(#ffffff, #12141a);. Important rules:

It only works when color-scheme is set, for example :root { color-scheme: light dark; }. Without it the function always returns the light value.
It accepts colors, so it is great for background, color, border-color and similar properties.
It removes the need for a separate media query block for simple palettes.
It follows the color-scheme of the element, so you can force a section to dark with color-scheme: dark and the colors inside switch automatically.
It is supported by modern browsers. Add a media query based fallback if you need older ones.

5. Manual Toggle with Three States

Some users want a site setting that differs from their system. Offer three choices: System, Light and Dark. With light-dark() the CSS is short: keep :root { color-scheme: light dark; } for System, then add :root[data-theme='light'] { color-scheme: light; } and :root[data-theme='dark'] { color-scheme: dark; }. All colors written with light-dark() follow the forced scheme. If you use variables and media queries instead, repeat the dark variables inside the media query for System and inside the data-theme selector for the manual choice.

6. Saving the Choice and Avoiding the Flash

Save the user choice with localStorage. To avoid a flash of the wrong theme, read the saved value in a small inline script in the head, before the CSS is painted, and set the data-theme attribute on the html element immediately. Wrap storage calls in try and catch because storage can be blocked. Also listen for changes of the system setting with matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...) when the user is in System mode.

7. Designing a Good Dark Palette

Avoid pure black #000 with pure white text. Use a very dark gray such as #12141a and an off-white such as #e8eaf0 to reduce glare.
Use elevation by lightness: higher surfaces such as cards and menus are slightly lighter than the page background, because shadows are hard to see on dark colors.
Lower the saturation of bright colors and use lighter tints of your brand color for links and buttons.
Do not just invert colors. Design each theme and check it.
Keep semantic meaning: error stays red, success stays green, but adjust the tone for contrast.

8. Contrast and Accessibility

WCAG requires a contrast ratio of at least 4.5 to 1 for normal text and 3 to 1 for large text and UI components, in both themes.
Test focus rings, borders, disabled states and placeholder text in dark mode.
Respect prefers-contrast: more and forced-colors: active with stronger borders and system colors.
Respect prefers-reduced-motion if you animate the theme change.
Do not rely on color only to show state.

9. Images, SVG and Media

Use the picture element with <source media='(prefers-color-scheme: dark)'> to load a different image for each theme, such as a logo with light text.
Soften bright photos in dark mode with filter: brightness(.85).
For inline SVG icons use fill: currentColor so they follow the text color.
Transparent PNGs with dark text may become unreadable, so test them on both backgrounds.

10. Other Useful Details

<meta name='theme-color'> accepts a media attribute, so the browser toolbar color can match each theme.
accent-color colors native checkboxes, radios and range inputs, and with light-dark() it works in both themes.
color-mix(in srgb, var(--primary) 20%, var(--bg)) creates consistent tints and hover colors from your variables.
Use transition: background-color .2s, color .2s for a smooth switch, and disable it for reduced motion.

11. Common Mistakes

Using light-dark() without setting color-scheme.
Hard coding colors in components instead of variables or light-dark().
Forgetting form controls, scrollbars and the page canvas, which stay light without color-scheme.
Loading the theme in a script at the end of the page and causing a flash.
Using pure black and pure white and creating eye strain.
Testing only one theme for contrast.
Ignoring images and logos that do not work on a dark background.

Key Takeaways

Set color-scheme to light dark, define colors with variables or light-dark(), follow the system by default and offer a saved manual override, set the theme early in the head to avoid a flash, design the dark palette with softer contrast and lighter elevation, and always check accessibility in both themes.

Try it Yourself HTML

<style>
  :root {
    color-scheme: light dark;
    --bg: #ffffff; --text: #1b1b1f; --card: #f1f5f9; --primary: #0b5fff;
  }
  @media (prefers-color-scheme: dark) {
    :root { --bg: #12141a; --text: #e8eaf0; --card: #1e222b; --primary: #6ea8ff; }
  }
  body { margin: 0; padding: 20px; font: 18px system-ui, sans-serif; background: var(--bg); color: var(--text); min-height: 100vh; }
  .card { background: var(--card); padding: 16px; border-radius: 12px; max-width: 360px; }
  a { color: var(--primary); }
</style>
<div class='card'><h3>Follows the system</h3><p>Change your OS theme and this card updates.</p><a href='#'>A themed link</a></div>
<p><input type='text' placeholder='Native input adapts'> <input type='checkbox' checked></p>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  :root { color-scheme: light dark; }
  body {
    margin: 0; padding: 20px; font: 18px system-ui, sans-serif; min-height: 100vh;
    background: light-dark(#ffffff, #12141a);
    color: light-dark(#1b1b1f, #e8eaf0);
  }
  .card {
    padding: 16px; border-radius: 12px; max-width: 360px;
    background: light-dark(#f1f5f9, #1e222b);
    border: 1px solid light-dark(#d0d7de, #2f3542);
  }
  a { color: light-dark(#0b5fff, #8ab4ff); }
  .forced-dark { color-scheme: dark; margin-top: 12px; background: light-dark(#fff, #0b0d12); color: light-dark(#111, #fff); padding: 12px; border-radius: 12px; max-width: 360px; }
</style>
<div class='card'>light-dark() picks the color by scheme. <a href='#'>Link</a></div>
<div class='forced-dark'>This box forces color-scheme: dark</div>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  :root { color-scheme: light dark; }
  :root[data-theme='light'] { color-scheme: light; }
  :root[data-theme='dark'] { color-scheme: dark; }
  body { margin: 0; padding: 20px; font: 18px system-ui, sans-serif; min-height: 100vh; background: light-dark(#fff, #12141a); color: light-dark(#1b1b1f, #e8eaf0); transition: background-color .2s, color .2s; }
  .bar { display: flex; gap: 8px; margin-bottom: 16px; }
  button { padding: 8px 14px; border-radius: 8px; border: 1px solid light-dark(#b8c0cc, #3b4252); background: light-dark(#f1f5f9, #1e222b); color: inherit; cursor: pointer; }
  button[aria-pressed='true'] { outline: 3px solid light-dark(#0b5fff, #8ab4ff); }
  @media (prefers-reduced-motion: reduce) { body { transition: none; } }
</style>
<div class='bar'>
  <button data-mode='system'>System</button>
  <button data-mode='light'>Light</button>
  <button data-mode='dark'>Dark</button>
</div>
<p>Current mode: <strong id='label'>system</strong></p>
<script>
  var root = document.documentElement;
  var label = document.getElementById('label');
  var buttons = document.querySelectorAll('button');
  function apply(mode) {
    if (mode === 'system') { root.removeAttribute('data-theme'); } else { root.setAttribute('data-theme', mode); }
    label.textContent = mode;
    buttons.forEach(function (b) { b.setAttribute('aria-pressed', b.dataset.mode === mode); });
    try { localStorage.setItem('theme', mode); } catch (e) {}
  }
  var saved = 'system';
  try { saved = localStorage.getItem('theme') || 'system'; } catch (e) {}
  apply(saved);
  buttons.forEach(function (b) { b.addEventListener('click', function () { apply(b.dataset.mode); }); });
</script>

Output

Press Run to execute.

Try it Yourself HTML

<!-- Put this small script in the <head>, before the CSS, to avoid a flash -->
<script>
  (function () {
    try {
      var saved = localStorage.getItem('theme');
      if (saved === 'light' || saved === 'dark') {
        document.documentElement.setAttribute('data-theme', saved);
      }
    } catch (e) {}
  })();
</script>
<meta name='color-scheme' content='light dark'>
<meta name='theme-color' content='#ffffff' media='(prefers-color-scheme: light)'>
<meta name='theme-color' content='#12141a' media='(prefers-color-scheme: dark)'>
<style>
  :root { color-scheme: light dark; }
  :root[data-theme='light'] { color-scheme: light; }
  :root[data-theme='dark'] { color-scheme: dark; }
  body { font: 18px system-ui, sans-serif; padding: 16px; background: light-dark(#fff, #12141a); color: light-dark(#1b1b1f, #e8eaf0); }
</style>
<p>The saved theme is applied before the first paint, so there is no flash.</p>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  :root { color-scheme: light dark; }
  body { margin: 0; padding: 20px; font: 18px system-ui, sans-serif; background: light-dark(#eef2f7, #0f1117); color: light-dark(#1b1b1f, #e8eaf0); }
  .surface-1 { background: light-dark(#ffffff, #171a22); padding: 16px; border-radius: 12px; max-width: 420px; }
  .surface-2 { background: light-dark(#f4f7fb, #1f232d); padding: 12px; border-radius: 10px; margin-top: 10px; }
  .btn { --primary: light-dark(#0b5fff, #8ab4ff); background: var(--primary); color: light-dark(#fff, #0b1020); border: 0; padding: 8px 14px; border-radius: 8px; }
  .tint { background: color-mix(in srgb, var(--primary, #0b5fff) 18%, transparent); padding: 10px; border-radius: 8px; margin-top: 10px; }
  .photo { display: block; width: 100%; height: 80px; border-radius: 8px; margin-top: 10px; background: linear-gradient(135deg, #ffd166, #ef476f); }
  @media (prefers-color-scheme: dark) { .photo { filter: brightness(.85); } }
  input[type=checkbox], input[type=range] { accent-color: light-dark(#0b5fff, #8ab4ff); }
</style>
<div class='surface-1'>Surface 1 (page card)
  <div class='surface-2'>Surface 2 is lighter in dark mode: elevation by lightness</div>
  <div class='tint'>color-mix() tint</div>
  <div class='photo'></div>
  <p><button class='btn'>Button</button> <input type='checkbox' checked> <input type='range'></p>
</div>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  body { font: 18px system-ui, sans-serif; padding: 16px; }
  picture img { width: 240px; height: 80px; border: 1px solid #888; border-radius: 8px; display: block; }
</style>
<p>A different logo file per theme with the picture element:</p>
<picture>
  <source media='(prefers-color-scheme: dark)' srcset="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='240' height='80'%3E%3Crect width='240' height='80' fill='%2312141a'/%3E%3Ctext x='120' y='48' font-size='28' text-anchor='middle' fill='white' font-family='sans-serif'%3EDark logo%3C/text%3E%3C/svg%3E">
  <img alt='Brand logo' src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='240' height='80'%3E%3Crect width='240' height='80' fill='white'/%3E%3Ctext x='120' y='48' font-size='28' text-anchor='middle' fill='black' font-family='sans-serif'%3ELight logo%3C/text%3E%3C/svg%3E">
</picture>

Output

Press Run to execute.

Try it Yourself JAVASCRIPT

var query = window.matchMedia('(prefers-color-scheme: dark)');

function describe() {
  return query.matches ? 'The system prefers dark.' : 'The system prefers light.';
}

console.log(describe());

query.addEventListener('change', function () {
  console.log('System theme changed. ' + describe());
});

console.log('Contrast targets: 4.5:1 for normal text, 3:1 for large text and UI parts.');

Output

Press Run to execute.

Exercise: Convert a Palette to light-dark()HTML

Set color-scheme: light dark on :root and rewrite the background, text and card colors with light-dark(). Use a dark gray such as #12141a for the dark background, not pure black.

Try it Yourself HTML

<style>
  body { font-family: system-ui, sans-serif; background: #ffffff; color: #1b1b1f; padding: 16px; }
  .card { background: #f1f5f9; border: 1px solid #d0d7de; padding: 16px; border-radius: 12px; max-width: 340px; }
</style>
<div class='card'>Make me support dark mode.</div>

Output

Press Run to execute.

Show expected output

The :root has color-scheme: light dark and body and card colors use light-dark(lightValue, darkValue)

This is a self-check — compare your result with the expected output above.

Exercise: Build a System, Light and Dark ToggleHTML

Add three buttons (System, Light, Dark). System removes the data-theme attribute. Light and Dark set data-theme on the html element. Use color-scheme in CSS so light-dark() follows the choice, and save the selection in localStorage inside a try and catch block.

Try it Yourself HTML

<style>
  :root { color-scheme: light dark; }
  body { font-family: system-ui, sans-serif; padding: 16px; background: light-dark(#fff, #12141a); color: light-dark(#1b1b1f, #e8eaf0); }
</style>
<button>System</button> <button>Light</button> <button>Dark</button>
<p>Toggle the theme.</p>

Output

Press Run to execute.

Show expected output

CSS rules for :root[data-theme='light'] and :root[data-theme='dark'] that set color-scheme, plus a script that sets or removes data-theme and stores the mode

This is a self-check — compare your result with the expected output above.

Was this page helpful?

CSS Dark Mode: prefers-color-scheme and light-dark()

Trending keywords covered in this lesson

1. How Dark Mode Works

2. The prefers-color-scheme Media Query

3. The color-scheme Property and Meta Tag

4. The light-dark() Function

5. Manual Toggle with Three States

6. Saving the Choice and Avoiding the Flash

7. Designing a Good Dark Palette

8. Contrast and Accessibility

9. Images, SVG and Media

10. Other Useful Details

11. Common Mistakes

Key Takeaways