Enabling Tailwind CSS Dark Mode with the Class Strategy: A Practical Guide

Desired Outcome

Enable Tailwind CSS dark mode using the class strategy, keep the CSS bundle lean, and verify that dark‑mode utilities are generated and applied when the .dark class is toggled.

Prerequisites

• Node.js 14+ installed.
• Tailwind CSS 3.x (JIT is default).
• Project structure with src/input.css and an index.html that imports the compiled CSS.

Procedure

1. Enable the Class Strategy in tailwind.config.js

module.exports = {
  darkMode: 'class', // <span class="comment"><code>media</code> is the default; switch to <code>class</code> for JS control.</span>
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    // Add any files that reference dark‑variant utilities.
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

2. Reference Dark‑Variant Utilities in Your Source

Tailwind’s purge removes unused classes. If a dark‑variant class is only referenced in a template string or a component that Tailwind can’t statically analyze, it will be stripped. Ensure all dark utilities appear in the content array or in literal class strings.

<div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100">
  <p>Hello, world!</p>
</div>

3. Build the CSS

Run Tailwind in watch mode to generate the output and keep it updated while you edit.

npx tailwindcss -i src/input.css -o dist/output.css --watch

In production, use NODE_ENV=production to trigger the purge.

NODE_ENV=production npx tailwindcss -i src/input.css -o dist/output.css

4. Verify Dark‑Mode Rules are Present

Open dist/output.css and search for a selector that starts with .dark. For example:

.dark .bg-gray-800{background-color:#1f2937;}

All expected utilities should have a corresponding .dark prefixed rule.

5. Toggle the .dark Class in the Browser

In index.html, add a button that toggles dark on the <html> element.

<button id="theme-toggle">Toggle Theme</button>
<script>
  const btn = document.getElementById('theme-toggle');
  btn.addEventListener('click', () => {
    document.documentElement.classList.toggle('dark');
  });
</script>

Open the page, click the button, and observe the background change. Inspect the element in devtools; the .dark .bg-gray-800 rule should now be applied.

Expected Checks

• Build output: Contains dark‑prefixed selectors for all utilities used.
• Runtime: Toggling .dark on a high‑level element flips the styles without page reload.
• Production build: Dark utilities remain after minification; if missing, verify the content array.

Recovery Options

• Missing dark utilities: Add the file to the content array or replace dynamic class names with static strings.
• Legacy browsers: If targeting IE11, avoid CSS variables or polyfill prefers-color-scheme support.
• Unintended styling: Keep the .dark class on the root element only; avoid adding it to individual components unless needed.

Limitations

• JIT mode generates dark variants on demand; if the .dark class is absent during the build, the class must still be referenced in the content array.
• Tailwind’s color system uses CSS variables for theming; browsers that lack support may not render the intended colors.
• Adding .dark to <html> affects all descendants; ensure components are built to respect the dark context.