I recently switched from SquareSpace to coding my own blog, which you can read about [here](/blog/hosting-your-own-website). One of the main reasons was so that I could add new cool stuff to my site; like a dark mode. I am surrounded by dark mode fanatics. I am not as die hard as some people I've met but I do like them and dark modes can be an important accessibility feature since they make your website easier on the eyes. This was originally going to be the first in my series of shorter posts but implementing a good dark mode turned out to be harder than I thought. I didn't just want to have any dark mode, I had some very specific goals in mind: - Use the device's default dark mode preference - Work at least partially without JavaScript - Allow the user to set their own custom preference - Remember the user's preference when they come back to the site ## Dark Modes in CSS Recently, Safari introduced a browser-wide dark mode as part of Apple's new system-wide dark mode feature. This dark mode preference is made available to web pages via a media query. For a detailed explanation, check out [this article](https://css-tricks.com/dark-modes-with-css/). The adoption across the web is [pretty good already](https://caniuse.com/prefers-color-scheme), even though it is just a draft right now. I love this feature because it makes for a great user experience to set your preference once and have it respected on every web page and app you use while giving web pages and apps the freedom to customize their themes. However, since it is still not fully supported it will also be important to make sure to have a manual setting for the user. The most basic way to use this feature to do your dark mode is: ```css @media (prefers-color-scheme: dark) { body { color: white; background-color: dimgrey; } } ``` This will detect the user's preference and change the background color and text color if a preference for dark mode is detected. Not only does this respect the user's preference but it takes effect immediately and works without JavaScript. This example doesn't use a great CSS strategy though. You may want more complicated color changes across your website when you change color schemes. Also, you may accidentally override these styles elsewhere in your CSS. To address this I used [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). I like to use these even without a dark mode since I generally have a few consistent styles that I want applied across my website. This way, if I want to color some text I can use `var(--text-color)` and my text will automatically be the correct text color I've chosen for my theme. CSS variables don't have perfect support yet either so you may want to include a fallback value but if a browser doesn't support them it almost certainly doesn't support `prefers-color-scheme` anyway. So the above example with variables may look something like: ```css /* Set the variables to their light mode values */ :root { --text-color: black; --background-color: white; } /* If the user's preferred color scheme is dark */ @media (prefers-color-scheme: dark) { /* Override the variables with their dark mode values */ :root { --text-color: white; --background-color: dimgrey; } } body { /* Define properties up here if you want fallback values */ color: black; background-color: white; /* If CSS variables are supported these will override the default values */ color: var(--text-color); background-color: var(--background-color); } ``` This looks a little clunkier in the tiny example but it makes dealing with bigger projects a lot easier. You can define as many properties as you want and use them in any stylesheet now. This CSS approach is pretty quick to do and will work for most of your users so this is not a bad place to stop if you want to. ## Overriding the System Some users may not have devices or browsers that support `prefers-color-scheme` or they may set a system preference for one mode but want to read the site in a different mode. Creating a button to override the current default solves both of these cases. It's also pretty cool. As far as I am aware there is no way to do this without JavaScript though. We need to update our website whenever the user changes their preference for dark mode. There are a lot of ways people do this, for example, some people use CSS classes. I felt the easiest way to do this was to define both color options as CSS variables with `dark-` or `light-` in front of them, then have a third variable for each color with `theme-` in front to store the current theme's value. This makes it easy to update our CSS variables with JavaScript but still gives us access to the values in CSS so our pure CSS dark mode still works. The variables make it obvious that you want to use the theme color and you want that color to change with the theme. To do this, first declare all of your CSS variables: ```css :root { /* Define the light mode values */ --light-text-color: black; --light-background-color: white; /* Define the dark mode values */ --dark-text-color: white; --dark-background-color: dimgrey; /* Set the theme variables to the light variable values by default */ /* These are the values the site is actually going to use */ --theme-text-color: var(--light-text-color); --theme-background-color: var(--light-background-color); } @media (prefers-color-scheme: dark) { :root { /* Set the theme variables to the dark mode values */ --theme-text-color: var(--dark-text-color); --theme-background-color: var(--dark-background-color); } } ``` Now we need to create a JavaScript function to change them: ```JavaScript // We'll need this query more than once now so let's save it // darkQuery.media updates when the media changes so can // re-use this variable without worrying about it getting stale const darkQuery = window.matchMedia("(prefers-color-scheme: dark)"); // We'll also need to convert our query to a theme a few times // I am not referencing darkQuery here because I will call // this on another query object later function toTheme(q) { return q.matches ? "dark" : "light"; } // Get our --theme variables // modified from: https://codepen.io/tylergaw/pen/jObmNNM const themeVariables = []; for (let sheet of document.styleSheets) { // If the style sheet is from the same domain if (!sheet.href || sheet.href.indexOf(window.location.origin) === 0) { for (let rule of sheet.cssRules) { // If tye rule is a style rule if (rule.type === 1) { for (let style of rule.style) { const name = style.trim(); if (name.indexOf("--theme") === 0) themeVariables.push(name); } } } } } // Create an empty __onThemeChange function // We can replace this with a different function somewhere // else on the site if we want that function to be called // whenever the theme changes window.__onThemeChange = function() {}; window.__setTheme = function(newTheme) { // Store the theme in a global variable so we can access the // current theme anywhere on the site window.__theme = newTheme; // Call our __onThemeChange function to notify any listeners window.__onThemeChange(newTheme); // Get the user's system color scheme const systemColorScheme = toTheme(darkQuery); // For each of our theme variables themeVariables.forEach(function (themeVariable) { // If the new theme is null, undefined, or the same as the system's theme if (!newTheme || newTheme === systemColorScheme) { // Remove our overriding variables to fall back to the CSS behavior document.documentElement.style.removeProperty(themeVariable); } else { // Set the current theme's variable to the new theme's variable // ex. --theme-text-color: var(--light-text-color) becomes: // --theme-text-color: var(--dark-text-color) const newValue = `var(${themeVariable.replace("theme", newTheme)})`; // Add our new variable setting to the document document.documentElement.style.setProperty(themeVariable, newValue); } }); } // If the user changes their system theme while they're on the site we // assume they want to change the theme so we update it darkQuery.addListener(function(e) { // Here we're using toTheme on e, this is why we didn't // reference darkQuery earlier when we defined it window.__setTheme(toTheme(e)); }); ``` Now you can call this function from whatever code you use to update your theme. I am not going to go too deeply into making the button because then this would be way way too much about dark modes. Also, my button is very Svelte-ey so this post would end up too Svelte specific. If your website doesn't reload the page when you navigate this theme will persist across pages. This will be the case for all of your classic Single Page Applications like your Reacts, your Angulars, your Vues, your Sveltes, ect... This should also work if you're using one of these with a Server Side Rendering framework like NextJS, Gatsby, or Sapper. Since I am using Svelte + Sapper this approach works for me between pages, but if your site does reload the page for navigation, you'll need to remember their setting just to persist it across page navigation so read on to learn how. ## Remembering If one of my visitors specifies that they want a certain color mode I don't want them to need to re-set it every time they come back to my site or refresh the page. The method for dealing with this is the same method for making the theme persist across page navigation for a site that reloads on navigation. To remember the user's preference we need to save it in local storage. This way it will live on the user's machine and our site can read the user's preferred theme and use it when they return. We can do this with just a few small tweaks to our JavaScript: ```JavaScript const darkQuery = window.matchMedia("(prefers-color-scheme: dark)"); function toTheme(q) { return q.matches ? "dark" : "light"; } const themeVariables = []; for (let sheet of document.styleSheets) { if (!sheet.href || sheet.href.indexOf(window.location.origin) === 0) { for (let rule of sheet.cssRules) { if (rule.type === 1) { for (let style of rule.style) { const name = style.trim(); if (name.indexOf("--theme") === 0) themeVariables.push(name); } } } } } window.__onThemeChange = function() {}; // Make setTheme not a global function anymore (not a property of window) // This function does the work of applying a theme, we need to call // this alone to apply our stored theme initially, but everywhere else // we want to both set the theme in storage and apply it so we // don't want to be able to call this elsewhere on the site function setTheme(newTheme) { window.__theme = newTheme; window.__onThemeChange(newTheme); const systemColorScheme = toTheme(darkQuery); themeVariables.forEach(function (themeVariable) { if (!newTheme || newTheme === systemColorScheme) { document.documentElement.style.removeProperty(themeVariable); } else { const newValue = `var(${themeVariable.replace("theme", newTheme)})`; document.documentElement.style.setProperty(themeVariable, newValue); } }); } try { // Grab the theme from local storage and use it to // initialize the preferred theme. If we can't find // it this will be null so setTheme will leave // the default CSS behavior. If local storage doesn't // work for whatever reason this will throw an error // which is caught and ignored and the default CSS // behavior will remain in place const storageTheme = localStorage.getItem("theme"); // If our theme is not one of the supported values for // whatever reason if (storageTheme !== "dark" && storageTheme !== "light") { // Remove the bad value (what can go wrong will go wrong...) localStorage.removeItem("theme"); } else { // Apply the preferred theme setTheme(storageTheme); } } catch (err) { } window.__setPreferredTheme = function(newTheme) { // Apply the new theme setTheme(newTheme); try { // Make sure the theme is one of our supported themes // This also ensures we don't store null or undefined. // Local Storage will actually convert null or undefined // to a string so saving it would wreak havoc. When the // values are saved they are falsey but when they are // read they are truthy so it can break some logic if (newTheme === "dark" || newTheme === "light") { // Set the theme in local storage. Just like before // we use a try/catch to ignore any errors from local storage localStorage.setItem("theme", newTheme); } } catch (err) {} } darkQuery.addListener(function(e) { // use __setPreferredTheme instead of __setTheme here window.__setPreferredTheme(toTheme(e)); }); ``` ## CSS Bonus Points: Transitions Changing the theme all at once can be a bit jarring. The change will look a bit nicer if you use some CSS transitions. You can add some CSS transitions wherever you use the theme variables. I am using a `transition-time` variable so the transition will be uniform across the site. I chose `.2s` for my transition time. Notice how `transition-time` does not have the `--theme` prefix. This is intentional because this variable does not change between light mode and dark mode. Here is an example of transitions on ``: ```CSS :root { --transition-time: .2s; } body { color: var(--theme-color); background-color: var(--theme-background-color); -webkit-transition: color var(--transition-time); -moz-transition: color var(--transition-time); -o-transition: color var(--transition-time); transition: color var(--transition-time); -webkit-transition: background-color var(--transition-time); -moz-transition: background-color var(--transition-time); -o-transition: background-color var(--transition-time); transition: background-color var(--transition-time); } ``` It's a little annoying to add this whenever you use a theme variable but as far as I can tell this is the best solution with my current setup. At first I put some transitions on `*` but on Chrome that sometimes caused a weird double transition. Also, you don't know what properties you may want to change without a transition or what properties you may want to add to your theme later so you can't really set it and forget it. For example, I set the global transition on `background-color` and `color` and one of my `border-color`s wasn't transitioning. This is the part I am least satisfied with so far so I will keep an eye out for something better and update it if I find something. I think if I went with a more sophisticated CSS solution (something like SASS) there would be a better solution for this but I don't think this is bad enough to warrant picking one and setting it up now. ## The Dreaded Blink So I had the dark mode implemented and I even had the blog post mostly written, but something was haunting me. If the user set their dark mode preference to be different than their device's and returned to the site they would see the wrong theme for an instant before it blinked to the right one. I was distraught; I can't stand UI blinks. A major reason I switched to hosting my own site is that my code's syntax highlighting blinked before loading and this dark mode thing was even worse. I looked at another web page I knew had a configurable dark mode, the [docker docs](https://docs.docker.com/engine/install/) and I noticed that on Firefox, at least sometimes, the page briefly flashes white on a page refresh if you have the dark mode configured. This was bad news. I started to think that if you have a static site there is just nothing you can do to avoid the blink in some cases. I thought that maybe you would need to use a cookie and render the dark mode or light mode on the server side to avoid it. But then, a glimmer of hope. I was on [Dan Abramov's blog](https://overreacted.io/) for unrelated reasons and I noticed that he had a configurable dark mode option. I refreshed the page and there was no blink. I inspected the network traffic, no cookie; he can't be doing this server side. I checked page's local storage and he had the theme stored there, just like I did. But how did he do it? He had no blog post on it so I inspected the source of his page and I found the secret that had been eluding me. I completely changed my approach and I re-wrote the top half of this blog post because of it. I ended up changing a lot from his original approach but it gave me the core of what I needed. What I found was that the very first element in the `` section of his HTML was an inline `

Posts