{"id":276,"date":"2026-05-25T05:04:03","date_gmt":"2026-05-25T05:04:03","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/tailwind-v4-dark-mode-from-config-to-one-css-line\/"},"modified":"2026-05-25T05:04:03","modified_gmt":"2026-05-25T05:04:03","slug":"tailwind-v4-dark-mode-from-config-to-one-css-line","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/tailwind-v4-dark-mode-from-config-to-one-css-line\/","title":{"rendered":"Tailwind v4 Dark Mode: From darkMode Config to One CSS Line"},"content":{"rendered":"

My designer pinged me on a Friday afternoon: ‘dark mode looks broken on the pricing page.’ It was not broken, exactly. It was stuck. I had upgraded that project to Tailwind v4 a week earlier, and my old darkMode: 'class'<\/code> line was sitting in a tailwind.config.js<\/code> file that v4 was not really reading anymore. Every dark:<\/code> utility had quietly stopped responding to the theme toggle. I had not noticed, because I had been testing in light mode like a professional.<\/p>\n

That afternoon sent me into how dark mode actually works in Tailwind v4. The short version: it got simpler, and the simplicity is the part that trips you up. There is no darkMode<\/code> key to set. The behavior you want now lives in your CSS, in one line. Here is the whole thing, including the part nobody warns you about.<\/p>\n

How dark mode worked before v4<\/h2>\n

In Tailwind v3, dark mode was a config decision. You opened tailwind.config.js<\/code> and picked a strategy:<\/p>\n

\/\/ tailwind.config.js  (Tailwind v3)\nmodule.exports = {\n  darkMode: "class", \/\/ or "media"\n  content: [".\/src\/**\/*.{html,js,jsx,ts,tsx}"],\n  theme: { extend: {} },\n};\n<\/code><\/pre>\n
\"media\"<\/code> meant dark:<\/code> utilities followed the operating system through the prefers-color-scheme<\/code> media query. \"class\"<\/code> meant they activated whenever a .dark<\/code> class appeared higher in the tree, which is what you needed for a manual toggle. You set it once and forgot about it for the life of the project.<\/p>\n
v4 broke that habit, because v4 moved configuration out of JavaScript and into CSS. If you have already been through that migration, I wrote up what broke when I moved to Tailwind v4<\/a>, and dark mode was not the only surprise waiting in there.<\/p>\n
The v4 way: a custom variant in your CSS<\/h2>\n
In v4, the default is prefers-color-scheme<\/code>. Import Tailwind, and dark:<\/code> utilities already follow the OS. No config, nothing to switch on.<\/p>\n
The catch is that the default is all you get for free. The moment you want a manual toggle, a button that flips the theme regardless of the OS, you override the dark<\/code> variant yourself. That happens in your CSS entry file, with @custom-variant<\/code>:<\/p>\n
\/* app.css *\/\n@import "tailwindcss";\n@custom-variant dark (&:where(.dark, .dark *));\n<\/code><\/pre>\n
That one line is the whole replacement for darkMode: 'class'<\/code>. It redefines what dark:<\/code> means. Instead of “when the OS is dark”, it now means “when a .dark<\/code> class exists on this element or an ancestor”. The :where()<\/code> wrapper holds specificity at zero, so your utilities still override cleanly.<\/p>\n
Your markup does not change at all:<\/p>\n
<html class="dark">\n  <body>\n    <div class="bg-white dark:bg-black">...<\/div>\n  <\/body>\n<\/html>\n<\/code><\/pre>\n
The official Tailwind dark mode docs<\/a> cover this, but it is easy to skim past. It is one line on a page you read once, and then forget you read.<\/p>\n
One thing worth knowing before you sprinkle dark:<\/code> across every component: in v4 you can often skip it. If your colors live as theme variables, you can redefine those variables once under the .dark<\/code> selector, in CSS, and most components just follow along. Writing dark:bg-black<\/code> on every card works, but it scatters the theme across your markup. Redefining a --color-surface<\/code> token under the dark selector keeps the decision in one file. I still use dark:<\/code> for real one-off tweaks, but the variable approach is what keeps a large UI consistent without me chasing stray colors.<\/p>\n
Class, data attribute, or media query<\/h2>\n
Three setups, and the choice is mostly about taste, not performance.<\/p>\n
The class strategy above is what I reach for most. It is terse, and it is what nearly every Tailwind tutorial and component library assumes you are using.<\/p>\n
If you would rather not put a state class on <html><\/code>, use a data attribute instead:<\/p>\n
@import "tailwindcss";\n@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));\n<\/code><\/pre>\n
Now dark:<\/code> responds to data-theme=\"dark\"<\/code>. I like this one on projects that already drive theming through data attributes, because the theme then lives in the same place as every other piece of UI state.<\/p>\n
And if a site only ever needs to follow the OS, do nothing. The v4 default already does that. I have shipped marketing sites where the entire “dark mode feature” was zero lines of code, and zero was the correct amount.<\/p>\n
The flash-of-wrong-theme problem<\/h2>\n
Here is the part nobody warns you about, and the real cause of my Friday bug once the dead config line was sorted.<\/p>\n
If you toggle dark mode with a class, something has to put that class on <html><\/code>. If you do that in a normal React effect, or a script at the end of <body><\/code>, the page first paints in light mode and then snaps to dark a moment later. That flash looks broken, and on a slow phone it is more than a moment.<\/p>\n
The fix is to set the class before the browser paints, with a small blocking script in the <head><\/code>:<\/p>\n
<head>\n  <script>\n    document.documentElement.classList.toggle(\n      "dark",\n      localStorage.theme === "dark" ||\n        (!("theme" in localStorage) &&\n          window.matchMedia("(prefers-color-scheme: dark)").matches)\n    );\n  <\/script>\n<\/head>\n<\/code><\/pre>\n
It reads the saved preference, falls back to the OS through window.matchMedia<\/code><\/a>, and sets the class synchronously. Yes, it is a blocking inline script, and yes, that is fine here. It runs in well under a millisecond, and it is the price of never showing the wrong theme. Every theme library you might reach for is doing some version of this same trick under the hood.<\/p>\n
A three-way toggle that respects the OS<\/h2>\n
Most real apps want three states, not two: light, dark, and “whatever the OS says”. The pattern that has held up for me stores an explicit choice in localStorage<\/code> only when the user makes one, and treats the absence of a value as “follow the OS”.<\/p>\n
\/\/ user picks light\nlocalStorage.theme = "light";\n\n\/\/ user picks dark\nlocalStorage.theme = "dark";\n\n\/\/ user picks "system": remove the override entirely\nlocalStorage.removeItem("theme");\n<\/code><\/pre>\n
The head script above then does the right thing in all three cases, because it checks localStorage<\/code> first and only consults matchMedia<\/code> when there is no stored override. The mistake I made early was writing the literal string \"system\"<\/code> into localStorage<\/code>. It works, but then you are hand-maintaining three string states and all the comparisons that go with them. Removing the key is cleaner: a value present means an explicit choice, a value absent means inherit from the OS.<\/p>\n
There is one more property worth setting that has nothing to do with Tailwind variants: color-scheme<\/code>. Telling the browser color-scheme: dark<\/code> makes it render native UI, scrollbars, form controls, date pickers, and the rest, in their dark variants. Without it you end up with a carefully themed dark page wearing a glaringly white scrollbar. Tailwind ships scheme-dark<\/code> and scheme-light<\/code> utilities for exactly this. I forgot it on two separate projects before the habit finally stuck.<\/p>\n
What I would change this week<\/h2>\n
If you are on Tailwind v4 already, open your CSS entry file and check for a @custom-variant dark<\/code> line. If it is not there and you have a theme toggle, that toggle is not working the way you think it is. That was my exact bug. Add the line, and the toggle starts responding again.<\/p>\n
If you are still on v3, dark mode by itself is not a reason to upgrade. It is a fair preview of how v4 feels, though: less configuration, and more of the behavior sitting in plain CSS where you can actually see it. I keep notes on the front-end setups I ship over on my portfolio<\/a>, and the pattern repeats everywhere, fewer config files and more defaults I can read at a glance. Dark mode in v4 is one line. Spend the hour you saved on picking colors that pass a real contrast check.<\/p>\n","protected":false},"excerpt":{"rendered":"
Tailwind v4 dropped the darkMode config key. Here is how dark mode works now: one CSS custom-variant line, the theme-flash fix, and a real system toggle.<\/p>\n","protected":false},"author":2,"featured_media":275,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Tailwind v4 dropped the darkMode config key. Here is how dark mode works now: one CSS custom-variant line, the theme-flash fix, and a real system toggle.","rank_math_focus_keyword":"tailwind dark mode","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[138,35],"tags":[37,135,38,139,36,134],"class_list":["post-276","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-frontend","category-web-development","tag-css","tag-dark-mode","tag-frontend","tag-tailwind","tag-tailwind-css","tag-tailwind-v4"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/276","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=276"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/276\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/275"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=276"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=276"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=276"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}