When I first added dark mode on my Gatsby projects, I encountered what you might know as the "Dark mode flashing" issue. The colors of the light mode would show up for a brief moment when refreshing a webpage.

Why does this issue show up? @JoshWComeau explains the reason behind this issue pretty well on his blog post CSS Variables for React Devs:

"Dark Mode" is surprisingly tricky, especially in a server-rendered context (like with Gatsby or Next.js). The problem is that the HTML is generated long before it reaches the user's device, so there's no way to know which color theme the user prefers.

To avoid this issue back when implementing it for the first time I did what I'd call an "ugly hack". I'd avoid rendering the whole website until the theme to render was known, and in the meantime, I'd just render a simple <div/>:

1
if (!themeState.hasThemeLoaded) {
10
const theme = themeState.dark ? theme('dark') : theme('light');

This ugly hack caused me some of the most frustrating problems I've had in a while, one of them even took me several days to figure out:

(Again thank you @chrisbiscardi for taking the time to help me debug this)

I then brought another solution to this problem: add a display: hidden CSS style to the main wrapper until the theme was loaded as featured in this blog post. It fixed my SEO issues, but I was still not satisfied with this fix.

After reading Josh Comeau's blog post on using CSS variables along with Emotion Styled Components, I decided to leverage these to fix the dark mode flashing issue once and for all (no hack this time!).

Originally I had my theme set to an object looking roughly like the following:

The cool thing I've learned recently is that it's possible to convert the hardcoded hex values to use CSS Custom Properties in a theme object that is passed to the Emotion Theme Provider.

The first thing to do add these CSS variables in a Emotion Global component:

1
import { css, Global } from '@emotion/core';
2
import React from 'react';
4
const GlobalStyles = () => (
8
        --theme-colors-gray: #f8f8f9;
9
        --theme-colors-black: #161617;
13
        --theme-colors-black: #161617;
14
        --theme-colors-white: #ffffff;
20
export default GlobalStyles;

Then, replace the hex values in the themes with the corresponding CSS variable names:

3
    background: var(--theme-colors-gray, #F8F8F9),
4
    body: var(--theme-colors-black, #161617),
7
    background: var(--theme-colors-black, #161617),
8
    body: var(--theme-colors-white, #FFFFFF),

Everything should remain pretty much the same, we've simply moved some hex values around and put them in CSS variables under their respective CSS class mode theme-light and theme-dark. Now let's see how this can be leveraged with some good old inline Javascript in a HTML script tag.

Server rendered websites like Gatbsy let us customize the html.js file. This gives us the possibility to inject a script that will set the proper theme based on the value present in local storage.

If not already available in the src folder the html.js can be copied from the .cache folder of your Gatsby project:

1
cp .cache/default-html.js src/html.js

The following will have to be added to this file:

3
    var mode = localStorage.getItem('mode');
5
      window.matchMedia('(prefers-color-scheme: dark)').matches === true;
6
    if (!mode && supportDarkMode) document.body.classList.add('theme-dark');
8
    document.body.classList.add('theme-' + mode);

This script does the following:

1. It looks for a local storage item with a key named mode

2. It looks for the prefers-color-scheme CSS media query, here we look whether its set to dark, which translates to the user loading the website having a system using dark mode.

3. If there's no mode set in local storage but the user's system uses dark mode, we add a class theme-dark do the body of the main document.

4. If there's simply no mode set in local storage we don't do anything, which will end up loading the default theme of our UI

5. Otherwise, we add the class associated with the mode set in local storage to the body of the document

We can add the script to the html.js file inside the <body> tag as follows:

2
<body {...props.bodyAttributes}>
3
  <script key="maximeheckel-theme" dangerouslySetInnerHTML={{ __html:
4
  `(function() { try { var mode = localStorage.getItem('mode'); var
5
  supportDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches
6
  === true; if (!mode && supportDarkMode)
7
  document.body.classList.add('theme-dark'); if (!mode) return;
8
  document.body.classList.add('theme-' + mode); } catch (e) {} })();`, }} />
9
  {props.preBodyComponents}
13
    dangerouslySetInnerHTML="{{"
18
  {props.postBodyComponents}

There's one last update to be done: updating the toggle light/dark mode function. We need to add a few lines of code to make sure we add or remove the appropriate CSS class from the body tag, otherwise the colors of our themes will be a bit messed up 😅.

In the example featured in the first blog post this is what the function looked like:

2
  const dark = !themeState.dark;
3
  localStorage.setItem('dark', JSON.stringify(dark));
4
  setThemeState({ ...themeState, dark });

And this is what we need to add to make it work properly again:

2
  const dark = !themeState.dark;
4
    document.body.classList.remove('theme-light');
5
    document.body.classList.add('theme-dark');
7
    document.body.classList.remove('theme-dark');
8
    document.body.classList.add('theme-light');
10
  localStorage.setItem('dark', JSON.stringify(dark));
11
  setThemeState({ ...themeState, dark });

By adding the code featured in the previous parts, we allow the Javascript related to getting the proper theme to be executed before we start rendering the React code. The appropriate class name to the body tag is going to be set immediately which will allow out CSS variables to be set to the proper variables. Then, for the brief moment when our "flash" issue previously occurred, the theme being used does not matter, as the colors are solely based on the CSS variables 🎉! This is what makes the flash disappear under the hood.