Tailwind CSS Dark Mode Decision Guide: Class vs Media

When adding dark mode to a Tailwind project you must decide between a class‑based toggle or relying on the prefers‑color‑scheme media query. This guide lists constraints, compares options, explains trade‑offs, and shows how to implement and verify the chosen solution.

Decision

When adding dark mode to a Tailwind project you must decide whether to use a class‑based approach (adding a dark class to the <html> element) or a media‑based approach (leveraging the prefers‑color‑scheme CSS media query). The decision hinges on two constraints:

Users must be able to toggle dark mode manually or rely on their system preference.
The implementation must work on legacy browsers (IE11+) as well as modern browsers.

Constraints

Manual toggle + system preference: The UI should allow a user‑initiated switch and also respect the OS setting.
Cross‑browser compatibility: Tailwind’s dark variant is available from 2.1+, but the prefers‑color‑scheme media query is not supported in IE11.
Performance & bundle size: Adding a small runtime JavaScript snippet is acceptable if it provides better UX.

Option Comparison

Feature	Class‑Based	Media‑Based
Implementation	Tailwind config: `darkMode: 'class'`; add `dark` class to `<html>` via JS or server render.	Tailwind config: `darkMode: 'media'`; use `@media (prefers-color-scheme: dark)` automatically.
Browser Support	All modern browsers + IE11 (class can be toggled via JS).	Modern browsers only; IE11 lacks `prefers-color-scheme`.
JS Required	Yes – a small snippet to toggle the `dark` class.	No – purely CSS.
Persistence	Can be stored in `localStorage` or cookies.	Relies on OS setting; no persistence possible.
Override System Preference	Yes – user toggle wins.	No – system preference is final.
Bundle Size Impact	Negligible – only a few lines of JS.	Zero – no JS.

Trade‑Offs

Class‑Based gives you full control and the ability to remember a user’s choice, but it adds a tiny JavaScript runtime. It also works on legacy browsers.
Media‑Based is lighter and requires no JS, but it cannot override the system preference and fails on IE11.

Concrete Implementation – Class‑Based Toggle

Configure Tailwind

In tailwind.config.js set:

module.exports = {
  darkMode: 'class', // or 'media' for the other option
  // ...other config
}

Add the dark class on page load

Server‑side rendering can add dark to <html> based on a stored preference. For client‑side, use a small script that runs before the page paints:

// init-dark-mode.js
(function () {
  const root = document.documentElement;
  const stored = localStorage.getItem('theme');
  if (stored === 'dark' || (!stored && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
    root.classList.add('dark');
  } else {
    root.classList.remove('dark');
  }
})();

Include this script in the <head> so it runs before the page renders.

Toggle button

Provide a UI element that flips the class and stores the choice:

function toggleDark() {
  const root = document.documentElement;
  if (root.classList.toggle('dark')) {
    localStorage.setItem('theme', 'dark');
  } else {
    localStorage.setItem('theme', 'light');
  }
}

Toggle Dark Mode

Styling in Tailwind
Use the dark: variant in your classes:
```
Hello, world!
```

Verification Steps

Check Tailwind version
Run npx tailwindcss -v and confirm it is ≥ 2.1.
Test class‑based toggle
Load the page, click the button, and observe the background and text colors change in dev tools. Verify that refreshing the page retains the chosen theme via localStorage.
Test media‑based fallback
Disable JavaScript, switch the OS theme to dark, and reload the page. The dark styles should apply automatically. In IE11, confirm that dark mode does not activate.

Limitations & Practical Checks

If you need to support IE11, the media‑based approach is insufficient. Stick with the class‑based method.
Always test in the target browsers after building the CSS to ensure the dark variant is present.
For very large projects, consider server‑side rendering the dark class to avoid a flash of light theme on first paint.

Conclusion

For a robust, user‑friendly dark mode that works everywhere and respects manual toggles, the class‑based approach is recommended despite the minimal JavaScript overhead. Use the media‑based option only if you can accept that legacy browsers and manual overrides are out of scope.

Choosing Dark Mode in Tailwind CSS: Class‑Based vs Media‑Based