Tailwind dark mode toggled with a class has no effect
TailwindCSS v3 manual dark mode ("class") doesn't work in Next.js projectShort 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.
Fix it fast
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 tailwindcss2Match what you see, then jump to its fix
- 1
The 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
You 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
The project uses @tailwind directives and tailwind.config.js has no darkMode key.v3 is still on the default media strategyFix - 4
The config is right but a component still stays light.The dark class is not on an ancestor of the elementFix
- 1
What does the error look like?
TailwindCSS v3 manual dark mode ("class") doesn't work in Next.js projectdark: 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.css2Fix
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
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/null2Fix
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 devConfirmed by tailwindcss.com
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 devConfirmed by v3.tailwindcss.com
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.className2Fix
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
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
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb 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 fixWeb 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 fixWeb apps
Tailwind classes have no effect in a Next.js app
Styles from Tailwind never reach the page after install
The page loads but Tailwind classes do nothing when the generated CSS never reaches the page.
5 causes, each with a fixWeb apps
A shadcn/ui Dialog stays open after the form is submitted
Form submits and the data saves, but the modal remains on screen
A shadcn Dialog is a Radix dialog.
3 causes, each with a fixWeb apps
Tailwind CSS 4 build fails on @apply in a Next.js project
Cannot apply unknown utility class
Tailwind 4 only knows its utilities in a stylesheet that imports Tailwind.
2 causes, each with a fix