Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Tailwind dark mode toggled with a class has no effect

ErrorTailwindCSS v3 manual dark mode ("class") doesn't work in Next.js project

Short answer

By default dark: follows the operating system setting. To drive it from a class you must tell Tailwind. In v4 add a @custom-variant dark rule in your CSS; in v3 set darkMode to selector (or class) in tailwind.config.js. The dark class must also sit on an ancestor such as the html element, and v4 does not read the old JS config by itself.

  • Applies to Next.js 15, Next.js 16, Tailwind CSS 3.4, Tailwind CSS 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which Tailwind major version you run, because the setting lives in a different place in each.

    npm ls tailwindcss
  2. 2Match what you see, then jump to its fix

    1. 1The project imports tailwindcss with @import and dark: works only when the OS is in dark mode.Tailwind v4 has no darkMode option, only a custom variantFix
    2. 2You upgraded to v4 and darkMode: 'class' is still in tailwind.config.js, yet it has no effect.A v3 tailwind.config.js is no longer read by v4Fix
    3. 3The project uses @tailwind directives and tailwind.config.js has no darkMode key.v3 is still on the default media strategyFix
    4. 4The config is right but a component still stays light.The dark class is not on an ancestor of the elementFix

What does the error look like?

  • TailwindCSS v3 manual dark mode ("class") doesn't work in Next.js project
  • dark: classes do nothing when the html element has class dark

Cause 1 of 4

Tailwind v4 has no darkMode option, only a custom variant

1Check

Open the global CSS file. If it has no @custom-variant line, dark: uses the prefers-color-scheme media feature.

grep -n "custom-variant\|@import" app/globals.css

2Fix

Override the dark variant so it matches the dark class on an ancestor.

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

3Verify

Add class dark to the html element in the browser dev tools and the dark: styles should appear.

document.documentElement.classList.toggle('dark')

Confirmed by tailwindcss.com

Did this fix it?

Cause 2 of 4

A v3 tailwind.config.js is no longer read by v4

1Check

Tailwind v4 does not detect JavaScript config files automatically. Look for an @config line in your CSS.

grep -rn "@config" app/ src/ 2>/dev/null

2Fix

Either move the setting to a @custom-variant (previous cause), or load the old config on purpose with @config.

/* app/globals.css */
@import "tailwindcss";
@config "../tailwind.config.js";

3Verify

Rebuild and toggle the dark class again.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

Cause 3 of 4

v3 is still on the default media strategy

1Check

Without the key, dark: follows the OS setting only.

grep -n "darkMode" tailwind.config.*

2Fix

Set darkMode to selector. From v3.4.1 selector replaced the class strategy; a custom selector can be given as a second array item.

// tailwind.config.js
module.exports = {
  darkMode: 'selector',
  // darkMode: ['selector', '[data-mode="dark"]'],
  content: ['./app/**/*.{js,ts,jsx,tsx,mdx}', './components/**/*.{js,ts,jsx,tsx,mdx}'],
}

3Verify

Restart the dev server, then toggle the dark class on the html element.

npm run dev

Confirmed by v3.tailwindcss.com

Did this fix it?

Cause 4 of 4

The dark class is not on an ancestor of the element

1Check

dark: utilities apply when the dark class is present earlier in the HTML tree. Inspect the element and check its parents.

document.documentElement.className

2Fix

Put the class on the html element, from the root layout or a small script that runs before paint.

// run once on load or when the theme changes
document.documentElement.classList.toggle(
  'dark',
  localStorage.theme === 'dark' ||
    (!('theme' in localStorage) &&
      window.matchMedia('(prefers-color-scheme: dark)').matches),
)

3Verify

Reload the page; the html element carries the class and the dark styles show.

document.documentElement.classList.contains('dark')

Confirmed by tailwindcss.com

Did this fix it?

How do I stop it coming back?

  • Write the dark rule once in the global CSS file and keep it next to the Tailwind import.
  • Set the theme class before first paint to avoid a light flash.
  • After a Tailwind major upgrade, read the upgrade guide before assuming old config keys still apply.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Hydration failed after adding next-themes dark mode

Console reports a server and client mismatch on the html element

next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.

3 causes, each with a fix

Web apps

Next.js fails with Cannot find module 'tailwindcss'

Error: Cannot find module 'tailwindcss'

Next.js loads Tailwind through PostCSS, so the error means the package named in postcss.config is not installed where the build runs.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.