Implementing a dark mode toggle in Next.js seems straightforward until you run into UI flickers, React hydration mismatch errors, or styling conflicts.
Instead of implementing this manually and fighting with local storage and system preferences, we will use a popular npm package called next-themes. We will also cover how to avoid common performance traps and how to configure this for the newest Tailwind CSS v4.
Let’s dive in!
Step 1: Install next-themes
First, we need to add the package to our project. You can use pnpm or npm:
Bash
pnpm add next-themes
# or
npm install next-themes
Step 2: Create the Theme Provider
Since Next.js App Router components are Server Components by default, we need a Client Component to handle our theme state.
Create a provider.tsx file in your ./app folder:
TypeScript
// app/provider.tsx
"use client";
import { ThemeProvider } from "next-themes";
export default function NextThemeProvider({ children }: { children: React.ReactNode }) {
return (
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{children}
</ThemeProvider>
);
}
Step 3: Wrap Your Layout
Next, modify your layout.tsx file by importing NextThemeProvider and wrapping your children with it.
Crucial Fix: Because
next-themesdynamically updates the<html>tag on the client side, it will trigger a React Hydration Mismatch error. You must addsuppressHydrationWarningto your<html>tag to safely prevent this error.
TypeScript
// app/layout.tsx
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import NextThemeProvider from "./provider";
const geistSans = Geist({
variable: "--font-geist-sans",
subsets: ["latin"],
});
const geistMono = Geist_Mono({
variable: "--font-geist-mono",
subsets: ["latin"],
});
export const metadata: Metadata = {
title: "Create Next App",
description: "Generated by create next app",
};
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html
lang="en"
className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
suppressHydrationWarning // <-- This is required!
>
<body className="min-h-full flex flex-col">
<NextThemeProvider>{children}</NextThemeProvider>
</body>
</html>
);
}
Step 4: Configure Tailwind CSS (The v3 vs v4 Gotcha)
How you configure Tailwind depends on the version you are using.
If you are using Tailwind v3: You must tell Tailwind to use class-based dark mode by adding darkMode: "class" to your tailwind.config.ts:
TypeScript
import { Config } from "tailwindcss";
const config: Config = {
darkMode: "class", // <-- Add this
content: [\
"./app/**/*.{js,jsx,ts,tsx}",\
// ...\
],
// ...
};
export default config;
If you are using Tailwind v4 (The Modern Way): Tailwind v4 ignores the config file by default. If you don’t explicitly tell it to look for the .dark class, your text colors won't change because Tailwind will stubbornly track your OS system preferences instead of your toggle button!
To fix this, open your app/globals.css and add a @custom-variant directive right below the Tailwind import:
CSS
/* app/globals.css */
@import "tailwindcss";
/* Force Tailwind v4 to use next-themes class-based dark mode */
@custom-variant dark (&:where(.dark, .dark *));
Step 5: The “Effect-Free” Theme Switcher
To toggle the theme, we destructure the useTheme hook.
Many developers use a useState and useEffect hook here to delay rendering the button until the client loads (the "mounted" pattern). Do not do this. Calling state synchronously in an effect causes a cascading render that hurts performance.
Instead, we can render both the “Light” and “Dark” labels statically and use Tailwind’s block dark:hidden classes to instantly show the correct one. This results in perfect hydration and zero flickers!
Create a ToggleThemeBtn.tsx in your components folder:
TypeScript
// components/ToggleThemeBtn.tsx
"use client";
import { useTheme } from "next-themes";
export function ToggleThemeBtn() {
const { resolvedTheme, setTheme } = useTheme();
return (
<button
onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
className="px-4 py-2 bg-gray-200 dark:bg-gray-800 text-black dark:text-white rounded-md transition-colors"
>
{/* This spans shows ONLY in light mode */}
<span className="block dark:hidden">Switch to Dark Mode</span>
{/* This spans shows ONLY in dark mode */}
<span className="hidden dark:block">Switch to Light Mode</span>
</button>
);
}
Conclusion
By relying on CSS to handle the UI swapping and ensuring we use the correct suppressHydrationWarning and Tailwind v4 directives, we've created a lightning-fast, flicker-free dark mode toggle.
No cascading React renders, no hydration errors, just a seamless user experience!