All posts
dark-modenext.jscssnext-themes

Dark Mode Done Right in Next.js

Nimesh FonsekaApril 19, 20267 min read
Dark Mode Done Right in Next.js

Dark mode is one of those features that's easy to get 80% right and hard to get fully right. The missing 20% is a flash of the wrong theme on page load, or a toggle that ignores the system preference, or colours that work in dark but break in light. This post covers how Gwan does it and how to replicate the same approach in your Next.js app.

The three problems

  1. Flash of unstyled content (FOUC) — On SSR, the server renders HTML with no knowledge of the user's saved theme. If you apply the theme in useEffect, the page flashes the wrong colour before hydration.
  2. System preference — prefers-color-scheme: dark should be respected on first visit, before the user has set a preference.
  3. Persistence — The chosen theme should survive page refreshes and navigation.

The solution: next-themes

next-themes solves all three by injecting a blocking script into <head> that reads localStorage and prefers-color-scheme before the page renders, and applies the .dark class synchronously. No flash.

Setup

npm install next-themes
// src/components/theme-provider.tsx
"use client";
import { ThemeProvider as NextThemesProvider } from "next-themes";
 
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  return (
    <NextThemesProvider
      attribute="class"
      defaultTheme="system"
      enableSystem
      disableTransitionOnChange
    >
      {children}
    </NextThemesProvider>
  );
}
// src/app/layout.tsx
import { ThemeProvider } from "@/components/theme-provider";
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

suppressHydrationWarning on <html> is required because next-themes adds the class server/client mismatch is expected.

The theme toggle

"use client";
 
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";
 
function SunIcon() {
  return (
    <svg viewBox="0 0 24 24" aria-hidden="true" className="size-4">
      <circle cx="12" cy="12" r="4" fill="currentColor" />
    </svg>
  );
}
 
function MoonIcon() {
  return (
    <svg viewBox="0 0 24 24" aria-hidden="true" className="size-4">
      <path
        fill="currentColor"
        d="M21 14.5A8.5 8.5 0 1 1 9.5 3a7 7 0 0 0 11.5 11.5z"
      />
    </svg>
  );
}
 
export function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
 
  // Avoid hydration mismatch — don't render until mounted
  useEffect(() => setMounted(true), []);
  if (!mounted)
    return <div className="w-8 h-8 rounded-sm bg-border animate-pulse" />;
 
  return (
    <button
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
      aria-label="Toggle theme"
    >
      {theme === "dark" ? <SunIcon /> : <MoonIcon />}
    </button>
  );
}

The mounted guard is the key insight — theme from useTheme() is undefined on the server, so you must wait for mount before rendering any theme-dependent UI.

How the CSS does the heavy lifting

Once .dark is on <html>, everything updates via CSS — no JS re-renders:

:root {
  --background: #f8f9f5;
  --foreground: #1c2218;
}
 
.dark {
  --background: #131a10;
  --foreground: #e2eada;
}
@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

All Tailwind utilities (bg-background, text-foreground) resolve to the correct CSS variable value for the active theme. The browser handles the cascade — zero JavaScript colour mapping.

Make dark: follow the class too

The tokens switch on .dark, but Tailwind v4's dark: variant doesn't. By default it uses @media (prefers-color-scheme: dark), so a dark: utility follows the operating system even when the user has picked light mode on your site. A few Gwan components use dark: utilities, such as placeholder colours and the elevated Card shadow, so this matters for them too. Tell Tailwind to use the class instead:

/* globals.css, right after @import "tailwindcss" */
@custom-variant dark (&:where(.dark, .dark *));

Now tokens and dark: utilities both follow the same .dark class that next-themes sets.

A real-world token system

Two variables is enough to prove the concept, but a production UI needs a full semantic palette — surfaces, borders, interactive states, status colours. Here are the semantic tokens used by gwan.dev. The numeric scales (primary, teal, emerald, rose, amber, neutral) live in the same @theme block and are not repeated here:

/* globals.css */
 
:root {
  --background: #f8f9f5;
  --foreground: #1c2218;
 
  --surface: #ffffff;
  --surface-raised: #eef2e8;
  --surface-overlay: #e3e9da;
 
  --border: #c4cdb8;
  --border-subtle: #d8dfce;
 
  --primary-default: #435240;
  --primary-default-fg: #f4f7f1;
  --primary-muted: #adc09e;
  --primary-muted-fg: #2c3629;
 
  --accent: #0f766e;
  --accent-fg: #f0fdfb;
 
  --muted: #e3e9da;
  --muted-fg: #60705a;
 
  --success: #047857;
  --success-bg: #ecfdf5;
  --success-fg: #064e3b;
 
  --danger: #be123c;
  --danger-bg: #fff1f2;
  --danger-fg: #881337;
 
  --warning: #b45309;
  --warning-bg: #fffbeb;
  --warning-fg: #78350f;
}
 
.dark {
  --background: #131a10;
  --foreground: #e2eada;
 
  --surface: #1c241a;
  --surface-raised: #252e22;
  --surface-overlay: #2d392a;
 
  --border: #3c4d38;
  --border-subtle: #2d392a;
 
  --primary-default: #adc09e;
  --primary-default-fg: #1c2218;
  --primary-muted: #435240;
  --primary-muted-fg: #e2eada;
 
  --accent: #2dd4bf;
  --accent-fg: #134e4a;
 
  --muted: #252e22;
  --muted-fg: #9ea593;
 
  --success: #34d399;
  --success-bg: #022c1e;
  --success-fg: #a7f3d0;
 
  --danger: #fb7185;
  --danger-bg: #200a10;
  --danger-fg: #fecdd3;
 
  --warning: #fbbf24;
  --warning-bg: #1c1300;
  --warning-fg: #fde68a;
}
 
@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-surface: var(--surface);
  --color-surface-raised: var(--surface-raised);
  --color-surface-overlay: var(--surface-overlay);
  --color-border: var(--border);
  --color-border-subtle: var(--border-subtle);
  --color-primary-default: var(--primary-default);
  --color-primary-default-fg: var(--primary-default-fg);
  --color-primary-muted: var(--primary-muted);
  --color-primary-muted-fg: var(--primary-muted-fg);
  --color-accent: var(--accent);
  --color-accent-fg: var(--accent-fg);
  --color-muted: var(--muted);
  --color-muted-fg: var(--muted-fg);
  --color-success: var(--success);
  --color-success-bg: var(--success-bg);
  --color-success-fg: var(--success-fg);
  --color-danger: var(--danger);
  --color-danger-bg: var(--danger-bg);
  --color-danger-fg: var(--danger-fg);
  --color-warning: var(--warning);
  --color-warning-bg: var(--warning-bg);
  --color-warning-fg: var(--warning-fg);
}

A few design decisions worth noting:

  • Semantic, not literal. --surface-raised describes intent, not a colour value. If you rebrand, you change the value in one place.
  • Foreground-background pairs. Each status colour (--success) comes with a background (--success-bg) and a legible foreground (--success-fg). You never have to guess what text colour reads well on a success badge.
  • The dark palette is not just inverted. Background gets darker, but --primary-default flips to the lighter end of the scale so primary buttons remain accessible on dark surfaces.

Swap the hex values for your own brand colours, keep the token names, and every component adapts automatically.

Don't want to write tokens by hand?

The gwan.dev/themes configurator lets you build your entire palette visually — pick your brand colour, tweak light and dark surfaces, adjust status colours, and watch every component update in real time. When you're happy, hit Copy CSS and it generates the :root, .dark, and primary-scale @theme block ready to drop into your globals.css. No manual hex juggling required.

Smooth transitions (optional)

disableTransitionOnChange in the provider prevents colour transitions when the theme changes (avoids a flash of transition). If you want a smooth fade:

Remove disableTransitionOnChange and add to your CSS:

*,
*::before,
*::after {
  transition:
    background-color 0.15s ease,
    border-color 0.15s ease,
    color 0.1s ease;
}

Apply this carefully — some interactive elements (buttons, inputs) feel laggy with colour transitions on them. Target only layout elements if needed.

System → manual → system

The three-way toggle (system → light → dark → system) gives users the best control:

"use client";
 
import { useTheme } from "next-themes";
 
const themes = ["system", "light", "dark"] as const;
 
export function ThemeCycleButton() {
  const { theme, setTheme } = useTheme();
  const current = themes.includes(theme as (typeof themes)[number])
    ? (theme as (typeof themes)[number])
    : "system";
  const next = themes[(themes.indexOf(current) + 1) % themes.length];
 
  return (
    <button type="button" onClick={() => setTheme(next)}>
      {current}
    </button>
  );
}

Most apps only need light/dark toggle, but if you want the system option exposed, this is the pattern.

What not to do

  • Don't use className={isDark ? "dark-class" : "light-class"} — it won't work with SSR
  • Don't apply theme in useEffect without the mounted guard — you'll get hydration warnings
  • Don't use @media (prefers-color-scheme: dark) in CSS alongside .dark {} — they'll conflict. That includes Tailwind's default dark: variant; switch it to the class with @custom-variant as shown above

Summary

ProblemSolution
Flash of wrong themenext-themes blocking script in <head>
System preferencedefaultTheme: "system" + enableSystem
Persistencenext-themes writes to localStorage
Hydration mismatchsuppressHydrationWarning on <html>, mounted guard on toggle
Colour switchingCSS custom properties on .dark class — zero JS
dark: utilities@custom-variant dark so they follow .dark, not the OS

Share this article

LinkedInX / Twitter

Written by

Nimesh Fonseka

More posts →