Skip header to navigation
When adding dark and light mode to your site, a common approach is to store the theme in localStorage and reading it on the next visit. But our JavaScript usually runs after the page loads, so reading it in JavaScript can cause a flash of the wrong theme—like flashbanging dark mode users with light mode. We can fix this with a small script in the <head>. But wait—isn’t that a blocking script? Aren’t those bad? Let’s take a quick look at why that’s not always true.
First, here’s the small simple script which you can add into the <head> of your document:
It reads the preferred theme from local storage and adds it as a data attribute to the <html> element, before the browser renders the site. We can now style our page for light and dark mode based on the html[data-theme=dark] selector.
Your site will only render after the script ran—so it will only render after the attribute is already set, and there will be no “initial flash of incorrect theme”, or FART.
…and to let users switch the theme, update both localStorage and the data-theme attribute.
If you have a server and not just a statically hosted site, you can also use a cookie. If you search online for how to avoid the initial flash, you’ll often find this solution: store the theme in a cookie and render the HTML on the server, with the theme already included in the server-rendered HTML.
A cookie gets rid of the blocking script that we use in the example above. A blocking script pauses the browser’s rendering process until the script is fully executed, which can delay the initial page load. We usually want to avoid such delays, which is why blocking scripts are often discouraged. But this doesn’t mean that a blocking script is always worse.
The downside of cookies is that you have to render the HTML on the server for every request, which also takes some time.
Caching is much easier without a cookie, and it significantly speeds up your site. You could even put a CDN in front of your HTML and cache your whole page. You can’t do that with a user-specific cookie. (Unless you’re Valve on a certain unforgettable Christmas morning in 2015.)
The blocking script takes only approximately 0.1ms to run. That’s 100 microseconds. There’s a chance that server-rendering your uncached HTML will take more time—several milliseconds or even seconds, depending on server and network conditions.
Here’s my take on it:
In the example above, we use as the default color scheme. If you want to default to the user’s preferred color scheme instead, but still let the user switch the theme, you could change it to something like this:
…or you could also add another value , as the default. It’s a bit more verbose which can be beneficial in certain situations, but can also make your selectors more complex.
It’s a bummer that we have to fall back to CSS selectors when we want to give a user control over the selected theme. The media query is neat, but even more so the new CSS color function. We can’t use them with a CSS-selector-based solution.
I like the ability to manually toggle the theme for a specific site. Just because I use dark mode on my system doesn’t mean that I want dark mode on every site. Especially for sites I visit and use a lot.
How about a small native API that allows us to override for the current site?
It would persist the user’s selection and let us use those nifty CSS features. The browser could even have a native UI to show the override to a user. It could let a user change or reset their preference directly in the browser’s UI, similar to camera and microphone permissions, without relying on toggles and buttons on the site itself.
A man can dream though… a man can dream.
When adding dark and light mode to your site, a common approach is to store the theme in localStorage and reading it on the next visit. But our JavaScript usually runs after the page loads, so reading it in JavaScript can cause a flash of the wrong theme—like flashbanging dark mode users with light mode. We can fix this with a small script in the <head>. But wait—isn’t that a blocking script? Aren’t those bad? Let’s take a quick look at why that’s not always true.
First, here’s the small simple script which you can add into the <head> of your document:
It reads the preferred theme from local storage and adds it as a data attribute to the <html> element, before the browser renders the site. We can now style our page for light and dark mode based on the html[data-theme=dark] selector.
Your site will only render after the script ran—so it will only render after the attribute is already set, and there will be no “initial flash of incorrect theme”, or FART.
…and to let users switch the theme, update both localStorage and the data-theme attribute.
If you have a server and not just a statically hosted site, you can also use a cookie. If you search online for how to avoid the initial flash, you’ll often find this solution: store the theme in a cookie and render the HTML on the server, with the theme already included in the server-rendered HTML.
A cookie gets rid of the blocking script that we use in the example above. A blocking script pauses the browser’s rendering process until the script is fully executed, which can delay the initial page load. We usually want to avoid such delays, which is why blocking scripts are often discouraged. But this doesn’t mean that a blocking script is always worse.
The downside of cookies is that you have to render the HTML on the server for every request, which also takes some time.
Caching is much easier without a cookie, and it significantly speeds up your site. You could even put a CDN in front of your HTML and cache your whole page. You can’t do that with a user-specific cookie. (Unless you’re Valve on a certain unforgettable Christmas morning in 2015.)
The blocking script takes only approximately 0.1ms to run. That’s 100 microseconds. There’s a chance that server-rendering your uncached HTML will take more time—several milliseconds or even seconds, depending on server and network conditions.
Here’s my take on it:
In the example above, we use as the default color scheme. If you want to default to the user’s preferred color scheme instead, but still let the user switch the theme, you could change it to something like this:
…or you could also add another value , as the default. It’s a bit more verbose which can be beneficial in certain situations, but can also make your selectors more complex.
It’s a bummer that we have to fall back to CSS selectors when we want to give a user control over the selected theme. The media query is neat, but even more so the new CSS color function. We can’t use them with a CSS-selector-based solution.
I like the ability to manually toggle the theme for a specific site. Just because I use dark mode on my system doesn’t mean that I want dark mode on every site. Especially for sites I visit and use a lot.
How about a small native API that allows us to override for the current site?
It would persist the user’s selection and let us use those nifty CSS features. The browser could even have a native UI to show the override to a user. It could let a user change or reset their preference directly in the browser’s UI, similar to camera and microphone permissions, without relying on toggles and buttons on the site itself.
A man can dream though… a man can dream.
<html data-theme={user.preferredTheme}>darksystemprefers-color-schemelight-dark()prefers-color-scheme<html data-theme="dark">
<head>
<!-- all the stuff in your head -->
<script>
(function () {
const theme = localStorage.getItem('theme') || 'dark';
document.documentElement.setAttribute('data-theme', theme);
})();
</script>
</head>
function toggleTheme() {
const newTheme =
document.documentElement.getAttribute('data-theme') === 'light'
? 'dark'
: 'light'
document.documentElement.setAttribute('data-theme', newTheme)
localStorage.setItem('theme', newTheme)
}
let theme = localStorage.getItem('theme');
theme ||= window.matchMedia('(prefers-color-scheme: dark)').matches
? 'dark'
: 'light';
document.documentElement.setAttribute('data-theme', theme);
// This does not exist
window.setUserPreference('color-scheme', 'dark')
<html data-theme={user.preferredTheme}>darksystemprefers-color-schemelight-dark()prefers-color-scheme<html data-theme="dark">
<head>
<!-- all the stuff in your head -->
<script>
(function () {
const theme = localStorage.getItem('theme') || 'dark';
document.documentElement.setAttribute('data-theme', theme);
})();
</script>
</head>
function toggleTheme() {
const newTheme =
document.documentElement.getAttribute('data-theme') === 'light'
? 'dark'
: 'light'
document.documentElement.setAttribute('data-theme', newTheme)
localStorage.setItem('theme', newTheme)
}
let theme = localStorage.getItem('theme');
theme ||= window.matchMedia('(prefers-color-scheme: dark)').matches
? 'dark'
: 'light';
document.documentElement.setAttribute('data-theme', theme);
// This does not exist
window.setUserPreference('color-scheme', 'dark')