skip to content

In Tailwind CSS v4, `dark:` utilities follow the OS setting although `<html>` has `class="dark"`; why, and how do you make them follow the class?

level: middleimportance: should knowfreq 15%

answer

  1. what dark: listens to by default
  2. a media feature, not a class
  3. override the dark variant in CSS
  4. @custom-variant with a :where() selector
  5. the v3 config switch is not read

basics

~20 s

Tailwind CSS v4's dark variant uses the prefers-color-scheme media query by default, so a dark class does nothing. Override it in CSS with @custom-variant dark (&:where(.dark, .dark *)); a data attribute works the same way.

solid answer

~40 s

Out of the box, Tailwind CSS v4 compiles `dark:bg-slate-900` inside `@media (prefers-color-scheme: dark)`, so the operating system decides and a `dark` class on `<html>` is ignored. In v3 you would set `darkMode: 'class'` in `tailwind.config.js`; v4 does not read that file unless you load it with `@config`, and the CSS-first way is to override the variant in your stylesheet: `@custom-variant dark (&:where(.dark, .dark *));` placed at the top level of the stylesheet that imports Tailwind. Now `dark:` applies to an element that has the class or sits inside one. For an attribute, write `@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));`. The `:where()` wrapper adds no specificity, so dark utilities compete with other utilities as before. How the class gets onto `<html>` and is remembered is application code, not Tailwind.

code

css · 7 lines
css
@import "tailwindcss";

/* dark: now follows <html class="dark"> instead of the OS setting */
@custom-variant dark (&:where(.dark, .dark *));

/* Alternative: an attribute such as <html data-theme="dark"> */
/* @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *)); */

go deeper

for a junior

Recall that dark: follows the operating system's prefers-color-scheme by default and that a one-line @custom-variant dark makes it follow a class or attribute.

for a middle

Explain the selector, why it matches the element and its descendants, why :where() keeps specificity at zero, and why v3's darkMode option is not read.

for a senior

Diagnose a toggle that does nothing from the compiled CSS, and handle an upgraded project whose dark switch still lives in a legacy JavaScript config.

for a principal

Decide whether the product follows the system setting, a class, or an attribute, and keep that one decision in a shared stylesheet rather than per-app configs.

## The symptom A yoga-studio booking app has a theme toggle. Clicking it adds `class="dark"` to `<html>`, and the markup uses `dark:bg-slate-900` and `dark:text-slate-100`. Nothing changes when the toggle is clicked, but the dark styles appear when the operating system switches to dark mode. ## The default: a media query Tailwind CSS v4 defines the `dark` variant as a **media variant**. In the framework source it is registered as `@media (prefers-color-scheme: dark)`, and the dark-mode documentation says the same: by default `dark:` follows the `prefers-color-scheme` media feature. So: - `dark:bg-slate-900` compiles to a rule inside `@media (prefers-color-scheme: dark)`. - A class on `<html>` is not part of that condition, so the toggle has no effect. ## The fix: override the variant in CSS Tailwind CSS v4 lets you redefine a variant with `@custom-variant`. The documented override for a class is: ```css @import "tailwindcss"; @custom-variant dark (&:where(.dark, .dark *)); ``` Now `dark:bg-slate-900` matches when the element itself has the `dark` class or sits inside an element that has it. The rule must be top-level: Tailwind's compiler rejects a nested `@custom-variant`. For a data attribute, the same pattern uses an attribute selector: ```css @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *)); ``` ## Why the selector looks the way it does | Part | Purpose | |---|---| | `&` | the element that carries the utility | | `.dark` inside `:where()` | matches the element if it has the class itself | | `.dark *` inside `:where()` | matches any descendant of an element with the class | | `:where(…)` | contributes zero specificity | Because `:where()` adds no specificity, `dark:bg-slate-900` keeps the same specificity as `bg-white`, so which one wins is decided by Tailwind's own ordering of the generated rules rather than by selector weight. ## What happened to v3's `darkMode` In v3 the switch lived in `tailwind.config.js`: - `darkMode: 'media'` was the default. - `darkMode: 'class'` compiled to `&:is(.dark *)`, which matches only descendants of `.dark` and adds the class's specificity. - `darkMode: 'selector'`, the later v3 option, compiled to the same `:where(.dark, .dark *)` shape v4 documents. In v4 a JavaScript config is no longer detected automatically. If you keep one and load it with `@config`, a compatibility layer still honours its `darkMode` setting; the upgrade tool (`npx @tailwindcss/upgrade`) converts it to a `@custom-variant dark` line when it migrates the config to CSS. ## What stays outside this switch The `@custom-variant` line answers only "what selects dark mode". Three related jobs belong elsewhere: 1. Writing `dark:` utilities in markup, and stacking them with other variants. 2. Getting the class onto `<html>` before first paint and remembering the user's choice; Tailwind's docs only sketch a script that toggles the class from `localStorage` and `matchMedia`. 3. Deciding whether dark mode should remap tokens or restyle components. A frequent combination: theme variables in `@theme` and a `.dark { --color-surface: … }` rule in base styles. Utilities reference `var(--color-surface)`, so they follow the class without any `dark:` prefix, and the custom variant is still needed for the cases where markup does use `dark:`. ## Choosing a class or an attribute Both overrides compile to the same shape; the choice is about what the application already sets: - A **class** (`.dark`) is the shortest and matches the documented examples. - A **data attribute** (`[data-theme=dark]`) leaves room for more than two values, such as a high-contrast theme, without overloading the class list. Whichever you pick, the selector in `@custom-variant dark` and the code that toggles the page must agree exactly: `data-theme="Dark"` does not match `[data-theme=dark]`. ## Checklist when dark mode does not toggle 1. Search the compiled CSS for `prefers-color-scheme`: if the dark rules sit inside it, the variant was never overridden. 2. Confirm the `@custom-variant dark` line is in the stylesheet that imports Tailwind, at the top level. 3. Confirm the selector matches what the app actually sets: a class, or an attribute with the exact value. 4. Check that a v3 `darkMode` option is not the only configuration left behind after an upgrade.

  • How does `&:where(.dark, .dark *)` differ from v3's `darkMode: 'class'` output?
    v3's class strategy compiled to `&:is(.dark *)`: it matched only descendants of a `.dark` element and added the class's specificity to the rule. The v4 documented selector also matches the element carrying the class and, through `:where()`, adds no specificity, so dark utilities keep the same specificity as other utilities.
  • After an upgrade, a project still has `darkMode: 'class'` in `tailwind.config.js` and no `@custom-variant`. Does class-based dark mode work?
    Only if the stylesheet loads that file with `@config`; Tailwind CSS v4 no longer detects a JavaScript config automatically. Without `@config` the option is never read and `dark:` falls back to `prefers-color-scheme`. Moving the switch to `@custom-variant dark` removes the dependency on the legacy file.

  • In Tailwind CSS v4, dark: follows a .dark class on html by default.
  • darkMode: 'class' in tailwind.config.js is picked up automatically in v4.
  • @custom-variant dark must go inside an @theme block.
  • The :where() wrapper raises specificity so dark utilities always win.
  • Setting color-scheme: dark on :root activates Tailwind's dark: utilities.

Assumes Tailwind CSS v4 (4.3.3 checked); v4 replaced v3's darkMode config option with overriding the dark variant via @custom-variant in CSS.