DEV Community: Ahmed Rabee

The Easiest Way to Implement Theme Toggling in React 19 using next-themes & Tailwind CSS v4

Ahmed Rabee — Tue, 26 May 2026 17:41:43 +0000

There is almost no React project today that doesn’t need at least two themes (Light and Dark). While you could build a custom theme toggle using the React Context API, it usually leads to complex boilerplate code just to handle system preferences and saving user choices.

Instead, we can use the incredibly popular NPM package next-themes. Despite the name, it works beautifully with plain React! While Next.js requires a bit more care with theming due to Server-Side Rendering (SSR) and hydration mismatches, setting this up in a React Single Page Application (SPA) is incredibly straightforward.

In this article, I will show you how to implement a seamless theme toggle using React 19, Vite, and the newly released Tailwind CSS v4.

Step 1: Create a New Vite Project

First things first, let’s create a new React project using Vite. Open your terminal and run:

pnpm create vite
# OR
npm create vite

Follow the prompts to select React and JavaScript/TypeScript. Once that’s done, install and configure Tailwind CSS v4 according to their official documentation.

Step 2: Configure Tailwind CSS v4 for Dark Mode

Tailwind v4 is CSS-first, meaning we handle configuration right inside our CSS file. To enable class-based dark mode, we just need to define a custom variant.

Open your ./src/index.css file and set it up like this:

/* ./src/index.css */
@import "tailwindcss";
/* Add this line to enable class-based dark mode */
@custom-variant dark (&:where(.dark, .dark *));

Step 3: Install Dependencies

Next, let’s install next-themes and a library for our theme icons (react-icons):

pnpm add next-themes react-icons
# OR
npm install next-themes react-icons

Step 4: Create the Theme Provider

Now, let’s create a wrapper component for our theme. This provider will wrap our entire application and inject the current theme into the HTML structure.

Create a new file called ReactThemeProvider.jsx:

// ./src/ReactThemeProvider.jsx
import { ThemeProvider } from "next-themes";
export default function ReactThemeProvider({ children }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      {children}
    </ThemeProvider>
  );
}

Note: By settingattribute="class" , we are tellingnext-themes to toggle thedark class on the<html> element, which works perfectly with our Tailwind configuration.

Step 5: Wrap Your App Component

Head over to your entry file and wrap the <App /> component with the provider we just created.

// ./src/main.jsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.jsx";
import ReactThemeProvider from "./ReactThemeProvider.jsx";

createRoot(document.getElementById("root")).render(
  <StrictMode>
    // wrap App component with ReactThemeProvider
    <ReactThemeProvider>
      <App />
    </ReactThemeProvider>
  </StrictMode>
);

Step 6: Create the Toggle Button

Finally, let’s create the button that users will click to toggle the theme. We will use the useTheme hook provided by next-themes to check the resolvedTheme (which calculates whether the system preference is currently light or dark) and switch it.

// ./components/ToggleThemeBtn.jsx
import { useTheme } from "next-themes";
import { LuSun, LuMoon } from "react-icons/lu";

export function ToggleThemeBtn() {
  const { resolvedTheme, setTheme } = useTheme();
  return (
    <button
      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
      className="p-2 rounded-md bg-slate-200 dark:bg-slate-800 text-slate-800 dark:text-slate-200 transition-colors"
      aria-label="Toggle theme"
    >
      {resolvedTheme === "dark" ? <LuSun size={20} /> : <LuMoon size={20} />}
    </button>
  );
}

And that is it! You now have a fully functioning, Tailwind-compatible theme toggle that respects user system preferences and saves their choices locally. Easy, right?!

How to Implement Dark/Light Mode with No Flickers in Next.js

Ahmed Rabee — Tue, 26 May 2026 17:35:35 +0000

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: Becausenext-themes dynamically updates the<html> tag on the client side, it will trigger a React Hydration Mismatch error. You must addsuppressHydrationWarning to 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!

DEV Community: Ahmed Rabee

The Easiest Way to Implement Theme Toggling in React 19 using next-themes & Tailwind CSS v4

Step 1: Create a New Vite Project

Step 2: Configure Tailwind CSS v4 for Dark Mode

Step 3: Install Dependencies

Step 4: Create the Theme Provider

Step 5: Wrap Your App Component

Step 6: Create the Toggle Button

How to Implement Dark/Light Mode with No Flickers in Next.js

Step 1: Install next-themes

Step 2: Create the Theme Provider

Step 3: Wrap Your Layout

Step 4: Configure Tailwind CSS (The v3 vs v4 Gotcha)

Step 5: The “Effect-Free” Theme Switcher

Conclusion

Step 1: Install `next-themes`