# Override the dark Variant, Don't Configure It **SHOULD** · **ID:** `design-dark-mode-class` · **Category:** design **Source:** [Tailwind](https://tailwindcss.com/docs) **Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/design-dark-mode-class > SHOULD: Use darkMode: "class" for user-controllable themes with light/dark/system options Redefine the dark variant with @custom-variant so a class can drive the theme, because the darkMode option no longer exists The `darkMode: 'class'` config option is gone — there is no config file to put it in. In v4 the `dark` variant is just a variant, and you change its behaviour by redefining it with `@custom-variant`. This repository is its own reference implementation: `src/index.css` line 7 reads `@custom-variant dark (&:is(.dark *));`, which is why toggling `.dark` on `` themes this entire app. The reason to override at all is unchanged: the default media-query variant reads the OS setting and nothing else, so a user who wants dark on a machine set to light has no way to ask for it and no way to persist the choice. Driving the variant from a class puts the decision in your hands — read `prefers-color-scheme` as the initial default, then let a toggle write `.dark` and store the preference. Note the selector shape: it must match both the `.dark` element itself and its descendants, otherwise `dark:` utilities on `` never fire. ## Bad — do not do this `design-dark-mode-class-bad` ```tsx export function DarkModeClassBad() { return (

Setting a config option that isn’t there

darkMode was removed in v4 along with the config file.

{`// tailwind.config.js — not read by v4
module.exports = {
  darkMode: 'class',
}`}

So the toggle does nothing

The dark variant still compiles to{' '} prefers-color-scheme.
Adding .dark to <html> changes nothing. The theme stays locked to the OS.
No error, no warning. The switch just never fires.

There is no darkMode option to set. The variant itself has to be redefined.

); } ``` ## Good — do this `design-dark-mode-class-good` ```tsx export function DarkModeClassGood() { return (

Override the variant in CSS

This is src/index.css line 7 of this very app.

{`@import "tailwindcss";

@custom-variant dark (&:is(.dark *));`}

The selector must match the .dark element and its descendants — otherwise{' '} dark: on <html> never fires.

Now a class drives the theme

{`document.documentElement.classList
  .toggle('dark', theme === 'dark');`}

Seed it from prefers-color-scheme, then let the user override and persist the choice.

The theme toggle at the top of this page works because of exactly this line.

); } ``` ## References - [Tailwind v4: Dark mode](https://tailwindcss.com/docs/dark-mode) - [Tailwind v4: @custom-variant](https://tailwindcss.com/docs/functions-and-directives)