The Quest for the Perfect Dark Mode

Dark Mode has become common enough that it's a user expectation. And yet, creating the perfect dark mode with a statically-built site/app is deceptively tricky. In this in-depth tutorial, we'll see how to build the perfect, flicker-free, customizable theming solution for React/Next.js apps.

JW

Josh W. ComeauJosh Comeau

·April 22, 2020

The Quest for the Perfect Dark Mode

Adding Dark Mode turned out to be the hardest part of building a statically-generated blog—harder than live-embedded code snippets, a unified GraphQL layer, or custom analytics.

The challenge stems from how frameworks like Next.js work: HTML is pre-generated ahead of time. If you are not careful, users will see a telltale flicker, with the wrong colors appearing for a brief moment before the correct theme loads.

This is a good reminder that even a seemingly simple feature can have a complex implementation in software development. The fix involves understanding both React hydration and CSS variables.

This post builds on two previous articles that are worth reviewing first, covering the perils of hydration and the role of CSS variables in theming.

The Perils of Hydration

Next.js and other SSR frameworks pre-generate HTML on the server. The article examines exactly how this process works and what implications it has for client-side interactivity, including theme switching.

JW

Written by

Josh W. Comeau

Josh Comeau

Writes for Josh Comeau. Part of the Tech Report engineering index.

All articles by Josh W. Comeau →