CSS Dark Mode
Many people set their phone or laptop to dark mode. With a few lines of CSS your website can follow their choice automatically.
How the Browser Knows
Operating systems such as Android, iOS, Windows and macOS have a light or dark setting. The browser passes this setting to CSS through the prefers-color-scheme media feature.
| Query | Matches when |
|---|---|
@media (prefers-color-scheme: dark) | The user chose dark mode |
@media (prefers-color-scheme: light) | The user chose light mode (or has no setting) |
Step 1: The color-scheme Property
First, tell the browser that your page supports both themes:
Example
:root {
color-scheme: light dark;
}The browser then makes its own parts dark too when needed: scroll bars, form fields, checkboxes and the default page background.
You can also use the meta tag in the <head>, so it works even before the CSS loads:
Example
<meta name="color-scheme" content="light dark">Step 2: Colours as Variables
The clean way to build themes is with CSS variables. Write your colours once, then change only the variables for dark mode.
Example
<!DOCTYPE html>
<html>
<head>
<style>
:root {
color-scheme: light dark;
--bg: #ffffff;
--text: #1f2937;
--card: #f1f5f9;
--brand: #264de4;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #0f172a;
--text: #e5e7eb;
--card: #1e293b;
--brand: #8aa4ff;
}
}
body {
background-color: var(--bg);
color: var(--text);
font-family: Arial, sans-serif;
padding: 16px;
}
.card {
background-color: var(--card);
padding: 16px;
border-radius: 8px;
}
h2 { color: var(--brand); }
</style>
</head>
<body>
<div class="card">
<h2>Ayesha's Online Store</h2>
<p>Switch your device to dark mode and run this again.</p>
</div>
</body>
</html>In dark mode, do not use pure black #000000 and pure white together. A very dark blue-grey background with light grey text is softer on the eyes. Bright brand colours often need a lighter shade on dark backgrounds to stay readable.
The light-dark() Function
Modern CSS has a shorter way. light-dark(light-value, dark-value) picks the first colour in light mode and the second in dark mode. It needs color-scheme to be set.
Example
<!DOCTYPE html>
<html>
<head>
<style>
:root {
color-scheme: light dark;
}
body {
background-color: light-dark(#ffffff, #111827);
color: light-dark(#1f2937, #e5e7eb);
font-family: Arial, sans-serif;
padding: 16px;
}
.btn {
background-color: light-dark(#264de4, #8aa4ff);
color: light-dark(white, #111827);
border: none;
padding: 10px 18px;
border-radius: 6px;
}
</style>
</head>
<body>
<h2>Course Registration</h2>
<button class="btn">Register</button>
</body>
</html>No media query is needed. light-dark() works only for colours, and it works in all modern browsers since 2024.
A Manual Theme Switch
Some users want dark mode only on your site. You can let them choose with a button. The trick: set color-scheme on the root element, and light-dark() follows it.
Example
<!DOCTYPE html>
<html>
<head>
<style>
:root { color-scheme: light dark; }
:root.light { color-scheme: light; }
:root.dark { color-scheme: dark; }
body {
background-color: light-dark(#ffffff, #0f172a);
color: light-dark(#1f2937, #e5e7eb);
font-family: Arial, sans-serif;
padding: 16px;
}
button { padding: 8px 14px; margin-right: 6px; }
</style>
</head>
<body>
<h2>Choose a theme</h2>
<button onclick="setTheme('light')">Light</button>
<button onclick="setTheme('dark')">Dark</button>
<button onclick="setTheme('')">Follow my device</button>
<p id="status">Theme: follows your device</p>
<script>
function setTheme(name) {
document.documentElement.className = name;
document.getElementById('status').innerHTML =
'Theme: ' + (name || 'follows your device');
}
</script>
</body>
</html>On a real site you would also save the choice with localStorage so it is remembered on the next visit.
Dark Mode Checklist
- Set
color-scheme: light darkon:root - Keep all colours in variables or
light-dark(), never hard-coded in many places - Check that text has enough contrast in both themes
- Make shadows softer or use lighter borders in dark mode, because dark shadows hardly show on a dark background
- Test images and logos: a dark logo can disappear on a dark background
Exercise
Exercise
What does color: light-dark(black, white) do when color-scheme is light dark?