Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Dark Mode and Theming

Dark Mode in Tailwind CSS

Add dark mode to a Tailwind CSS site with the dark: variant, follow the system setting, switch to a class or data-attribute toggle and remember the choice.

Many people prefer dark interfaces at night, or all the time. Tailwind makes dark mode a matter of one extra prefix: dark:bg-slate-900 applies a background only when dark mode is active. There are two common ways to decide when it is active: follow the operating system, or let the user choose with a toggle button. This lesson covers both, plus a small script that remembers the choice without a flash of the wrong theme.

The dark: variant follows the system by default

Out of the box, dark: uses the CSS media query prefers-color-scheme: dark. If the person's operating system or browser is in dark mode, every dark: utility turns on. You do not need any JavaScript.

HTML
<div class="bg-white text-slate-900 dark:bg-slate-900 dark:text-slate-100">
  Adapts to the system theme.
</div>

The pattern is always the same: write the light version with plain utilities first, then add dark: overrides only for the properties that change. Colors that already work in both themes (an accent blue, for example) need no dark: twin.

A card with light and dark styles

If your system is light, you see the light version. The next section gives you a button to force either one.

A manual toggle with @custom-variant

To let the user choose, tell Tailwind to ignore the media query and look at something in the HTML instead. In v4 you do it with @custom-variant, redefining what dark: means. The most common choice is a dark class on the <html> element.

CSS
@import "tailwindcss";

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

Read it as: "the dark variant applies to an element that has the dark class, or lives inside an element that has it". With that in place, adding class="dark" to <html> turns the whole page dark. Removing it turns it back.

Some teams prefer a data attribute, which is just as easy:

CSS
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

In the browser build used in the examples on this site, the same rule goes in a <style type="text/tailwindcss"> block.

A dark mode toggle button

Here the class sits on a wrapper div so the demo stays inside its preview; on a real site you put it on <html>, so <body>, dialogs and portals are covered too.

Remembering the choice

A complete toggle has three parts: respect the system on a first visit, let the user override, and save the override. The code below is the usual recipe. It is shown read-only because previews run in a sandbox without localStorage.

HTML
<script>
  // Run in <head>, before the page paints, to avoid a flash of the wrong theme.
  const saved = localStorage.getItem('theme');
  const systemDark = matchMedia('(prefers-color-scheme: dark)').matches;
  document.documentElement.classList.toggle('dark', saved ? saved === 'dark' : systemDark);

  function setTheme(mode) {          // 'light', 'dark' or 'system'
    if (mode === 'system') localStorage.removeItem('theme');
    else localStorage.setItem('theme', mode);
    document.documentElement.classList.toggle(
      'dark',
      mode === 'dark' || (mode === 'system' && matchMedia('(prefers-color-scheme: dark)').matches)
    );
  }
</script>

Keep this script small and put it in the <head>, not at the end of the body. If it runs late, the page paints light for a moment and then flips to dark, which is the "flash" users notice.

Also tell the browser which schemes the page supports with color-scheme. The utilities scheme-light, scheme-dark and scheme-light-dark set it, so built-in controls such as scrollbars and checkboxes match: <html class="scheme-light dark:scheme-dark">.

Designing a good dark theme

Dark mode is not "invert the colors". A few habits pay off:

  • Avoid pure black backgrounds. slate-900 or slate-950 is easier on the eyes and lets shadows and borders remain visible.
  • Lower the contrast of large text areas slightly: dark:text-slate-300 for body text, dark:text-white for headings.
  • Replace shadows with borders or rings in dark mode, because a dark shadow on a dark page is invisible: shadow dark:shadow-none dark:ring-1 dark:ring-white/10.
  • Tone down saturated accents. A strong indigo-600 button may need dark:bg-indigo-500.
  • Check images and logos. A dark logo needs a light version, for example with dark:hidden and hidden dark:block on two images.

Instead of repeating these pairs in every element, you can define semantic colors once and let them change with the theme. That is the subject of Multiple Themes with CSS Variables.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. With no configuration, when does dark:bg-black apply in Tailwind v4?

    The default dark variant uses the prefers-color-scheme: dark media query.
  2. 2. Which directive lets you switch dark mode to a CSS class?

    @custom-variant redefines what the dark: prefix matches, here an element that has or sits inside .dark.
  3. 3. Why should the theme script run in the head?

    Running before first paint avoids a visible switch from light to dark.
  4. 4. Which is a good dark-mode practice?

    Shadows disappear on dark backgrounds, and extreme contrast tires the eyes.

Summary

  • dark: follows prefers-color-scheme by default.
  • Redefine it with @custom-variant dark (...) to use a .dark class or a data attribute and add your own toggle.
  • Save the choice in localStorage and apply it from a small script in the <head> to avoid a flash.
  • Design dark colors deliberately: soft backgrounds, lowered contrast, borders over shadows.

Next: The @theme Directive