What is dark mode?
Dark mode is a colour scheme with light text on a dark background. Many people prefer it, especially in low light or at night, and phones, tablets and computers all now let users switch their whole device to dark mode.
A good dark mode does two things: it automatically matches the visitor's device setting, and it lets them override that choice on your site if they prefer. In this guide we'll build both, step by step. Here's the finished result. Try the buttons:
Choose a theme above. “System” follows your device’s own light or dark setting.
You'll need a basic understanding of HTML and CSS to follow along.
Step 1: store your colours in custom properties
The key to an easy dark mode is to never write colours directly into your rules. Instead, store them in custom properties (CSS variables) on the :root element, which is the <html> element, and use var() everywhere else:
:root {
--bg: #ffffff;
--surface: #f1f5f9;
--text: #1f2937;
--muted: #4b5563;
--accent: #1d4ed8;
--border: #e5e7eb;
}
body {
background: var(--bg);
color: var(--text);
}
header {
background: var(--surface);
border-bottom: 1px solid var(--border);
}
a {
color: var(--accent);
}
Now switching to dark mode only means changing those few variables. Every rule that uses them updates automatically.
Tip: name variables by their role, such as --bg or --text, rather than their colour, such as --white. In dark mode, --white would end up being dark grey, which gets confusing fast.
Step 2: follow the visitor's system setting
The prefers-color-scheme media query tells you whether the visitor's device is set to light or dark mode. Use it to swap in dark values for your variables:
:root {
color-scheme: light dark;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #121826;
--surface: #1e2737;
--text: #e5e7eb;
--muted: #9ca3af;
--accent: #93c5fd;
--border: #334155;
}
}
With just this, your site automatically follows the device's setting, with no JavaScript and no button needed.
What does color-scheme do?
The color-scheme property tells the browser which schemes your page supports. In dark mode, the browser then draws its own parts of the page to match: scrollbars, form fields, checkboxes and the default page background. Without it, you can end up with bright white form fields on your dark page.
Correction: the original version of this post said it used a media query to apply dark mode, but its code only switched themes with a button and never checked the visitor's system setting. Following prefers-color-scheme as above means visitors who already use dark mode get it straight away.
Step 3: let visitors choose
Some people want a different theme on your site from the rest of their device. A theme switcher with three options (System, Light and Dark) handles every case.
The HTML
<div role="group" aria-label="Colour theme">
<button type="button" value="system" aria-pressed="true">System</button>
<button type="button" value="light" aria-pressed="false">Light</button>
<button type="button" value="dark" aria-pressed="false">Dark</button>
</div>
aria-pressed tells screen readers (software that reads pages aloud) which button is currently selected.
The CSS
The visitor's choice is stored as a data-theme attribute on the <html> element. These rules let it override the system setting:
/* Forced dark: same values as the media query */
:root[data-theme="dark"] {
color-scheme: dark;
--bg: #121826;
--surface: #1e2737;
--text: #e5e7eb;
--muted: #9ca3af;
--accent: #93c5fd;
--border: #334155;
}
/* Forced light: undo the media query */
:root[data-theme="light"] {
color-scheme: light;
--bg: #ffffff;
--surface: #f1f5f9;
--text: #1f2937;
--muted: #4b5563;
--accent: #1d4ed8;
--border: #e5e7eb;
}
The JavaScript
A few lines handle the clicks and remember the choice for next time using localStorage, which keeps small pieces of data in the visitor's browser:
<script>
const buttons = document.querySelectorAll('[aria-label="Colour theme"] button');
function setTheme(theme) {
if (theme === 'system') {
document.documentElement.removeAttribute('data-theme');
localStorage.removeItem('theme');
} else {
document.documentElement.dataset.theme = theme;
localStorage.setItem('theme', theme);
}
buttons.forEach(button => {
button.setAttribute('aria-pressed', button.value === theme);
});
}
buttons.forEach(button => {
button.addEventListener('click', () => setTheme(button.value));
});
setTheme(localStorage.getItem('theme') || 'system');
</script>
Avoiding a flash of the wrong theme
If the saved theme is applied by a script at the end of the page, visitors may briefly see the wrong colours as the page loads. To prevent this, add a tiny script inside the <head>, before your stylesheet loads:
<head>
<script>
const saved = localStorage.getItem('theme');
if (saved) document.documentElement.dataset.theme = saved;
</script>
<link rel="stylesheet" href="styles.css">
</head>
A modern shortcut: light-dark()
Newer browsers support the light-dark() function, which takes two colours and automatically uses the first in light mode and the second in dark mode. It follows color-scheme, so you can write each colour once, side by side, with no media query:
:root {
color-scheme: light dark;
--bg: light-dark(#ffffff, #121826);
--surface: light-dark(#f1f5f9, #1e2737);
--text: light-dark(#1f2937, #e5e7eb);
--muted: light-dark(#4b5563, #9ca3af);
--accent: light-dark(#1d4ed8, #93c5fd);
--border: light-dark(#e5e7eb, #334155);
}
/* The visitor's choice just changes color-scheme */
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }
That's the whole theme system, and the demo at the top of this post uses exactly this approach. light-dark() is supported in all current major browsers. If you need to support older ones, use the media query method from step 2.
Designing a good dark theme
A dark theme is more than swapping black and white. These tips make it comfortable to read:
- Avoid pure black. A very dark grey or navy, such as
#121826, is easier on the eyes than#000000, and lets you show depth with slightly lighter surfaces. - Avoid pure white text. A soft off-white, such as
#e5e7eb, reduces glare against a dark background. - Lighten your accent colours. A strong blue that works on white can be hard to read on dark grey. Use a lighter, softer version, like
#93c5fd. - Check contrast in both themes. Text should have a contrast ratio of at least 4.5 to 1 against its background in light and dark mode.
- Rethink shadows. Dark shadows barely show on a dark page. Use lighter surfaces or subtle borders to separate elements instead.
- Tone down images. Very bright photos can be dazzling in dark mode. A gentle filter can help:
img { filter: brightness(0.9); }inside your dark theme.
Good to know: dark mode is often said to reduce eye strain, but research on that is mixed, and some people, including many with astigmatism, find light text on dark backgrounds harder to read. That's why letting visitors choose matters more than picking the "right" theme for them.
The complete code
Here's a complete, modern setup using light-dark(), with a smooth transition when the theme changes:
:root {
color-scheme: light dark;
--bg: light-dark(#ffffff, #121826);
--surface: light-dark(#f1f5f9, #1e2737);
--text: light-dark(#1f2937, #e5e7eb);
--muted: light-dark(#4b5563, #9ca3af);
--accent: light-dark(#1d4ed8, #93c5fd);
--border: light-dark(#e5e7eb, #334155);
}
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }
body {
margin: 0;
font-family: system-ui, sans-serif;
background: var(--bg);
color: var(--text);
transition: background-color 0.3s, color 0.3s;
}
header {
display: flex;
justify-content: space-between;
align-items: center;
padding: 1rem;
background: var(--surface);
border-bottom: 1px solid var(--border);
}
a { color: var(--accent); }
@media (prefers-reduced-motion: reduce) {
body { transition: none; }
}
Combine it with the HTML and JavaScript from step 3, including the small script in the <head>.
Wrapping up
Store your colours in custom properties, follow the visitor's device with prefers-color-scheme or light-dark(), and offer a System, Light and Dark switcher that remembers their choice. Add color-scheme so form fields match, check contrast in both themes, and your site will look great whatever time of day it is.