← Back to CSS Course | Chapter 9: Modern CSS Features | Lesson 20 of 25

CSS Dark Mode

Imagine reading on a bright tablet screen in a completely dark room. The bright white background can hurt your eyes and cause strain. HTML Dark Mode solves this issue. It is a design setting that allows your webpage colors to adapt automatically to match your user's system preferences or manual theme choices. By adjusting your color schemes to use dark backgrounds and comfortable text contrast in low-light environments, you protect your readers' eyesight and reduce battery consumption on mobile devices.

In this page:

  1. The prefers-color-scheme Query
  2. Using CSS Variables for Dark Mode
  3. The color-scheme Meta Tag
  4. Manual Class Toggles
  5. Dimming and Inverting Images/Icons
Syntax
css 
@media (prefers-color-scheme: dark) {
  :root {
    --variable-name: value;
  }
  body {
    background-color: color;
    color: color;
  }
}

The prefers-color-scheme Query

The prefers-color-scheme media query allows your webpage to detect automatically if a visitor has enabled dark mode in their device settings. This enables you to apply dark styling rules directly in CSS without needing JavaScript.

Note:
  • Use prefers-color-scheme to configure automated, eye-friendly dark mode themes on load.
  • Accepted values:
  • @media (prefers-color-scheme: dark) — dark preference
  • @media (prefers-color-scheme: light) — light preference
  • no-preference — historical value, usually unmatched
  • note: reflects the OS or browser setting
Warning: Failing to check system preferences can force a bright white layout on users who prefer comfortable dark themes.

Example: The prefers-color-scheme Query

css 
<style>
body { font-family: sans-serif; padding: 1rem; }
@media (prefers-color-scheme: dark) {
  body {
    background: #111;
    color: #eee;
  }
}
</style>
<p>Switch your OS to dark mode and this page turns dark.</p>

Using CSS Variables for Dark Mode

Instead of writing duplicate style rules for every element, you can define your page colors using CSS custom properties (variables) inside the root selector. To switch themes, you simply update your variables in one central place.

Note:
  • Use CSS variables to make updating and maintaining your dark mode themes quick and easy.
  • Accepted values:
  • :root { --bg: ...; } — light values
  • @media (prefers-color-scheme: dark) { :root { --bg: ...; } } — dark values
  • var(--bg) — consumers stay unchanged
  • color-scheme: light dark — native UI matches
Warning: Ensure your color variables have high contrast in both themes to keep your content readable.

Example: Using CSS Variables for Dark Mode

css 
<style>
body { font-family: sans-serif; padding: 1rem; }
:root {
  --bg: white;
  --text: black;
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: black;
    --text: white;
  }
}
body {
  background: var(--bg);
  color: var(--text);
}
</style>
<p>Colors follow your OS light/dark setting.</p>

The color-scheme Meta Tag

The color-scheme meta tag or CSS property tells the browser that your webpage supports both light and dark themes, allowing scrollbars and form buttons to adjust automatically. scrollbar-color goes a step further than the automatic color-scheme adjustment by letting you manually set the exact thumb and track colors of the scrollbar, useful when your dark theme uses custom brand colors rather than the browser's default dark scrollbar palette.

Note:
  • Declare the color-scheme meta tag inside your head section to ensure the browser loads it early.
  • Accepted values:
  • color-scheme: normal — default, no declared color scheme (browser renders light)
  • color-scheme: light — light only
  • color-scheme: dark — dark only
  • color-scheme: light dark — supports both
  • meta name="color-scheme" — the HTML equivalent
  • inherit | initial | unset | revert — CSS-wide keywords accepted by every property
Warning: Failing to declare this can leave scrollbars displaying in bright white on an otherwise dark page.

Example: The color-scheme Meta Tag

css 
<style>
body { font-family: sans-serif; padding: 1rem; color-scheme: light dark; }
<head>
  <meta name="color-scheme" content="light dark">
</head>
</style>
<!-- The meta tag goes in <head>; here it is shown with a themed page -->
<meta name="color-scheme" content="light dark">
<p>Form controls and scrollbars follow your OS theme.</p>
<input placeholder="A themed input">

Manual Class Toggles

While system preferences are convenient, users often want a manual toggle button to switch themes. You can handle this by using JavaScript to apply a custom class (like '.dark-mode') to your html tag, and styling that class inside your CSS.

Note:
  • Save the user's manual theme selection in localStorage so their preference persists across visits.
  • Accepted values:
  • .dark { ... } — class applied to html or body
  • [data-theme="dark"] — attribute approach
  • classList.toggle(dark) — JavaScript toggle
  • localStorage — remember the choice
Warning: Make sure your manual toggle button is accessible to keyboard users who cannot navigate with a mouse.

Example: Manual Class Toggles

css 
<style>
body {
  background: white;
  color: black;
}
body.dark-mode {
  background: black;
  color: white;
}
</style>
<body class="dark-mode">Toggled via a JS-added class</body>

Dimming and Inverting Images/Icons

Bright white images and illustrations can look jarring on a dark page. You can use CSS filters to dim your images slightly or invert icons in dark mode to keep them from looking too bright.

Note:
  • Apply a slight opacity filter to your images in dark mode to soften their brightness and blend them into the page.
  • Accepted values:
  • filter: brightness(0.8) — dims an image
  • filter: invert(1) — inverts an icon
  • opacity: 0.85 — softens an image
  • filter: none — resets
  • inherit | initial | unset | revert — CSS-wide keywords accepted by every property
Warning: Do not invert standard photographic images, as it will distort their colors and make them look like negatives.

Example: Dimming and Inverting Images/Icons

css 
<style>
body { font-family: sans-serif; padding: 1rem; }
@media (prefers-color-scheme: dark) {
  img {
    opacity: 0.85;
  }
}
</style>
<img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='80'%3E%3Crect width='120' height='80' fill='%23f90'/%3E%3C/svg%3E" alt="Sample image">
Live Example
Related Topics

CSS Pagination (Print) · CSS Accessibility · CSS Print Styles · CSS Performance

{# common_mistakes/chapter_summary/browser_support: on Hindi pages the view already swaps in the hi_ translation fields (or blanks these out if untranslated), so this renders correctly for both languages without a lang_code check here. #}
Common Mistakes
  1. Forgetting to include prefers-color-scheme support, forcing a bright white theme on low-light readers.
  2. omitting the color-scheme meta tag, which leaves scrollbars and inputs displaying in bright white in dark mode.
  3. Using pure black (#000) and pure white (#fff) values, which can create a harsh, high-contrast display that strains eyes.
Chapter Summary
  • HTML Dark Mode can be detected automatically using the prefers-color-scheme media query.
  • The color-scheme meta tag instructs the browser to style scrollbars and native inputs to match the active theme.
  • Use CSS variables for easy theme styling, and customize or dim your images using CSS filters to prevent blinding glare.
Browser Support

Standard prefers-color-scheme queries and color-scheme meta tags are natively supported by all modern browsers.

🔒

Chapter Quiz — Complete all 25 topics to unlock

0/25 topics done

Complete these topics first:

← Previous Lesson CSS Pagination (Print) Next Lesson → CSS Accessibility

Login to run this code

C/C++/Java/PHP execution requires a free account. Your code is saved — you'll land right back in the editor after logging in.