This article covers the basics of setting up a dark mode colour scheme: how to tell the browser which schemes your site supports, and how to provide light and dark values.
It focuses on following the user's system preference. A manual light and dark toggle involves some additional steps, so it is not covered here.
For guidance on what to check once dark mode is in place, such as contrast, images, borders and shadows, see the dark mode checklist.
What is dark mode?
Dark mode is a display setting that uses darker background colours and lighter text and interface elements. It provides an alternative colour scheme for people who prefer it or find it more comfortable.
It is a complete colour scheme that can affect colours, images and other parts of an interface.
How do system preferences reach the page?
- The operating system has a light or dark appearance setting.
- The browser reads that preference and makes it available through
prefers-color-scheme. - CSS can then use that preference to apply light or dark styles.
It is important to remember that prefers-color-scheme only tells you what the user prefers. The site still needs to provide the corresponding styles.
Declare which colour schemes you support
Start by declaring the colour schemes your site supports. You can do this in the <head>, in CSS, or both.
Step 1: Add a meta element (optional)
You can declare the colour scheme in the <head>. The browser reads the meta element before the stylesheet loads, so it can use the right page colour from the start and avoid a flash of the wrong colour.
<meta name="color-scheme" content="light dark">Declare the colour schemes your site is designed to support. If you use light dark, make sure your own colours and styles work correctly in both modes.
If the site supports light mode only, you can declare that instead. For example, content="only light" tells the browser to keep the page in light mode rather than applying its own dark mode adjustments.
Step 2: Declare color-scheme in CSS
color-scheme tells the browser which colour schemes your page supports. This lets browser-provided elements, such as form controls and scrollbars, match the current scheme.
:root {
color-scheme: light dark;
}The browser uses whichever of these schemes matches the user's current setting. The order only matters when there is no preference to match, in which case the first value is used.
This declares the same supported colour schemes as the meta element in Step 1. The meta element arrives earlier because it does not wait for the stylesheet to load. The CSS version is easier to keep alongside the rest of your styles. You can use one or both, but if you use both, make sure the values match.
Provide light and dark values
Declaring color-scheme handles the browser's own elements. Your own colours still need light and dark values.
Step 3: Choose how to provide light and dark values
There are two ways to do this. You can use either one, or mix them on the same site.
Option A: prefers-color-scheme
Use prefers-color-scheme to apply dark mode styles when the user's system is set to dark mode.
@media (prefers-color-scheme: dark) {
/* dark mode styles */
}Your normal styles are used by default, and the styles inside the media query are applied when dark mode is preferred.
Option B: light-dark()
light-dark() lets you provide a light value and a dark value together, without repeating them in a media query.
:root {
color-scheme: light dark;
--text-color: light-dark(#1a1a1a, #e6e6e6);
--background-color: light-dark(#fff, #1f1f1f);
}
body {
color: var(--text-color);
background: var(--background-color);
}The first value is used for light mode and the second for dark mode. For paired colour values, this gives the same result as Option A in fewer lines.
light-dark() relies on color-scheme, so make sure Step 2 is in place when using it.
light-dark() is newer than prefers-color-scheme, so check browser support if you need to support older browsers.
Set the browser interface colour
Step 4: Add theme-color meta elements (optional)
The theme-color meta element can suggest a colour for parts of the browser interface, such as the toolbar or title bar. It does not change the colours of the page itself.
<meta
name="theme-color"
content="#ffffff"
media="(prefers-color-scheme: light)"
>
<meta
name="theme-color"
content="#1a1a1a"
media="(prefers-color-scheme: dark)"
>Support varies between browsers, and the effect is most noticeable on mobile. Treat this as an optional enhancement rather than a required step.
Simple! Now go forth and darken your site.