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:

The prefers-color-scheme Query
Using CSS Variables for Dark Mode
The color-scheme Meta Tag
Manual Class Toggles
Dimming and Inverting Images/Icons

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.

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

@media (prefers-color-scheme: dark) {
  body {
    background: #111;
    color: #eee;
  }
}

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.

Warning: Ensure your color variables have high contrast in both themes to keep your content readable.

Example: Using CSS Variables for Dark Mode

css

:root {
  --bg: white;
  --text: black;
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: black;
    --text: white;
  }
}
body {
  background: var(--bg);
  color: var(--text);
}

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.

Warning: Failing to declare this can leave scrollbars displaying in bright white on an otherwise dark page.

Example: The color-scheme Meta Tag

css

<head>
  <meta name="color-scheme" content="light dark">
</head>

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.

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.

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

@media (prefers-color-scheme: dark) {
  img {
    opacity: 0.85;
  }
}

Common Mistakes

Forgetting to include prefers-color-scheme support, forcing a bright white theme on low-light readers.
omitting the color-scheme meta tag, which leaves scrollbars and inputs displaying in bright white in dark mode.
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