The dark: Variant

Many people switch their phone or computer to dark mode: dark backgrounds and light text everywhere. It is easier on the eyes in a dark room, and lots of people simply prefer it. More and more websites have a dark version too, and in this lesson, our shelter's site gets one.

We've prepared a smaller version of the home page: a header, the main heading, three cats and a footer. It's styled with the classes from the previous lessons, and so far, it's only light. By the end of this lesson, it will have a dark version and a button that switches between the two.

Tailwind has a variant for dark mode: dark:. It works like hover: and md:. A class with this prefix applies only in dark mode. A pair of classes gives an element one color for each mode:

<body class="bg-stone-50 dark:bg-stone-900">

In light mode, the page is almost white (bg-stone-50). In dark mode, both classes apply, and dark:bg-stone-900 wins: Tailwind puts the CSS of variants after the plain classes, and of two equally specific rules, the later one wins (you know that from the cascade in the CSS course).

How does the browser know which mode is on? Visitors choose it in the settings of their operating system, and a page can ask about it with an @media rule. By default, Tailwind wraps the CSS of dark: classes in one, just as it does for md:, only this one asks about the system setting instead of the width:

@media (prefers-color-scheme: dark) {
	.dark\:bg-stone-900 {
		background-color: oklch(21.6% 0.006 56.043);
	}
}

That's often good enough. But many sites let visitors choose with a button, however their system is set, and a page can't change the system setting. That's why sites with a switch turn dark mode on with a class: dark mode is on when the <html> element has the class dark. A script then only adds or removes that class. We'll do it the same way. While you work on the page, you'll turn dark mode on and off by writing or deleting a single class, without changing your computer's settings.

To tell Tailwind, add this line to style.css, right after the import:

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

@custom-variant defines a variant, here a new version of dark. The parentheses hold the selector it adds: & stands for the element that has the dark: class, and :where(.dark, .dark *) means "which has the class dark itself, or is inside an element that has it" (.dark * is a descendant selector, as you know it from the CSS course). dark:bg-stone-900 then makes this rule:

.dark\:bg-stone-900:where(.dark, .dark *) {
	background-color: oklch(21.6% 0.006 56.043);
}

Every element of the page is inside <html>, so class="dark" on it turns dark mode on for the whole page. You don't have to learn the line by heart: you'll find it in Tailwind's documentation (search for "dark mode").

The class dark doesn't style anything itself: it's only a signal for the dark: classes. And watch out for typos: with class="drak", nothing happens, and no error appears.