Is it Possible to Avoid the Flash of Unstyled Text When Light Mode is the Default and Dark Mode is Selected?

[gkapfham]

Description

Thanks for developing the Quarto framework, I really appreciate it!

I'm currently working on re-implementing my own web site using Quarto. I wanted to draw attention to the fact that any Quarto-based web site that has a light/dark mode seems to have a flicker. Specifically, I noticed that once you select dark mode and then navigate to other pages on the site, there is always a slight flicker when the page renders. By "flicker" what I mean is that the page loads the light background and then it is replaced with the dark background.

I have tested this primarily on Linux and Android and several different browsers, including Brave, Chrome, and Firefox. I always notice the flicker in a predictable fashion. Do other people see a brief per-page flicker when you view your sites in dark mode?

Here are some examples of other sites that are using Quarto and also have the described flicker when the site's default is light mode and you are browsing pages using dark mode:

• https://www.andreashandel.com/
• https://myphd.netlify.app/

Finally, I should note that if you check the light/dark mode toggling feature that is built-in to Bootstrap, as documented at this web site:

https://getbootstrap.com/

I do not ever see the flicker that I am talking about if I am in dark mode and I navigate to any page on the Bootstrap web site, even pages that include images or a lot of content.

I should note that I've checked the source code that Quarto generates and it seems like this is the code that this is what controls the switch to dark mode.

<script>
var darkSwitch = document.getElementById("darkSwitch");
window.addEventListener("load", function () {
  if (darkSwitch) {
    initTheme();
    darkSwitch.addEventListener("change", function () {
      resetTheme();
    });
  }
});

/**
 * Summary: function that adds or removes the attribute 'data-theme' depending if
 * the switch is 'on' or 'off'.
 *
 * Description: initTheme is a function that uses localStorage from JavaScript DOM,
 * to store the value of the HTML switch. If the switch was already switched to
 * 'on' it will set an HTML attribute to the body named: 'data-theme' to a 'dark'
 * value. If it is the first time opening the page, or if the switch was off the
 * 'data-theme' attribute will not be set.
 * @return {void}
 */
function initTheme() {
  var darkThemeSelected =
    localStorage.getItem("darkSwitch") !== null &&
    localStorage.getItem("darkSwitch") === "dark";
  darkSwitch.checked = darkThemeSelected;
  darkThemeSelected
    ? document.body.setAttribute("data-theme", "dark")
    : document.body.removeAttribute("data-theme");
}

/**
 * Summary: resetTheme checks if the switch is 'on' or 'off' and if it is toggled
 * on it will set the HTML attribute 'data-theme' to dark so the dark-theme CSS is
 * applied.
 * @return {void}
 */
function resetTheme() {
  if (darkSwitch.checked) {
    document.body.setAttribute("data-theme", "dark");
    localStorage.setItem("darkSwitch", "dark");
  } else {
    document.body.removeAttribute("data-theme");
    localStorage.removeItem("darkSwitch");
  }
}
</script>

I can see that this code is very similar to the code that is described in this issue:

coliff/dark-mode-switch#22

However, I still see the flicker in a predictable fashion. My rough understanding of the discussion in the aforementioned issue tracker and other reading that I've done on the issue is that some part of the above JavaScript is not being loaded "early enough" to prevent the flash of unstyled text like, for instance, the light background in my light mode being loaded and then replaced by the dark background in the dark mode.

Is there any way to avoid this flicker when using Quarto? If you have time, please let me know what you think! Again, I really appreciate all of the time and effort that everyone is investing in Quarto; it is fast becoming my favorite framework for web development and I look forward to its continued development.

Finally, if there are details that I have not provided or a way in which I can further help to diagnose this problem or solve it, please let me know and I will try to help as my expertise and schedule permits. Thanks in advance for any response that you can provide.

[dragonstyle]

Thanks for putting together a thorough topic / discussion. We are definitely aware of the flash when toggling between dark and light mode (and we are definitely not fans of it). Your basic summary (we're not toggling 'early enough') is a good summary of the issue - when we render the HTML itself, we place render using the default value for dark vs light that was provided via the theme yaml. If the user toggles to a different mode, we essentially start to display the page using the default value, then see the local storage value for the user which indicates to use the other mode, then we decorate the body of the document and switch the stylesheets.

We've looked a bunch of different ways to fix this, but none of the straightforward approaches have worked for us. I think to truly fix it will take use a day or two and we'll need to find a different approach to the toggling than we have now. It's on my radar to try to tackle for the 1.4 release of Quarto, though I'm not 100% certain I will make it...

[dense-set]

@dragonstyle Is it fixed in v1.4? (This could be the definitive reason I switch to the pre-release version.)

[dragonstyle]

Not yet, sorry!

[mcanouil]

@dense-set It's no longer a pre-release. 1.4 entered the "release candidate" state which means 1.4 is the default version for download and that the stable 1.4 will be out very soon (only very minor changes or regression fix occurs in this stage).
So not sure "This could be the definitive reason I switch to the pre-release version." really applies.

[dragonstyle]

You can track it here:

• Custom theme sass file for light mode unexpectedly applied to dark mode #3705

[mcanouil]

FYI:

• Merging `@media prefers-color-scheme` and Quarto Dark Theme Toggle #2588

[gkapfham]

Hi @mcanouil, thanks for this reminder! Yeah, the flashing that I normally see is a little like what I see in the movie on that page, except perhaps it is less pronounced.

[mcanouil]

Closing the thread as outdated.
Follow up on:

• Custom theme sass file for light mode unexpectedly applied to dark mode #3705

[gordonwoodhull]

More exactly

• Flashing when switching between pages in dark theme.  #1325

Fixed in 1.7.