Tailwind Class Not Applying — Why It Happens and How to Fix It

Tailwind's Just-in-Time engine generates CSS on demand rather than shipping the entire utility class library. In Tailwind v2, the approach was to ship all utilities and use PurgeCSS to strip unused ones. In v3, the JIT engine replaced this model entirely: it scans your source files to discover which class names you actually use, then generates only those CSS rules. This produces dramatically smaller bundles — typically 5–20 KB of gzipped CSS instead of hundreds of kilobytes.

The scanning process is text-based. Tailwind reads each file listed in the content configuration as a string and uses pattern matching to find anything that looks like a Tailwind class name. It does not parse or execute your JavaScript, HTML, or template files. This is why the content paths matter so much — a file not listed in content is never read, and its classes are never generated.

The scanner looks for patterns that match complete Tailwind class names: strings that match utility prefixes followed by values from your theme config. It will find p-4 in className="p-4" or class="p-4" or even in a comment or a data attribute. It will not find p-4 if the string is constructed at runtime as 'p-' + size, because the text p-4 never appears in the source file.

In Tailwind v4, the configuration format changed significantly. Instead of a tailwind.config.js file, v4 uses CSS-first configuration with @theme in your main CSS file. The content detection is also smarter in v4 — it uses a Rust-based scanner that is faster and can detect patterns in more contexts. However, v3 and v4 configs are not compatible, and upgrading without reading the migration guide is a common cause of all classes disappearing.

Start in the browser's DevTools. Open the Elements panel, click on the element that should have the class applied, and check the Styles pane. If the class name appears in the class attribute but there is no corresponding rule in the Styles list, the class was not generated. The browser received HTML with the class name but no CSS that matches it.

Search the generated CSS bundle for the missing class name. In a Next.js or Vite project, look in the .next/static/css/ or dist/assets/ directories for the compiled CSS file. Open it and search for the class. If it is absent, the JIT scanner did not detect it. If it is present, the issue is specificity — some other rule is overriding it — and you need to check the cascade, not the Tailwind config.

To verify your content paths, add a console.log to your build process or use Tailwind CLI with the --watch flag and observe which files it scans. Alternatively, open tailwind.config.js and mentally walk through each glob pattern, then check whether the file containing the missing class is matched by at least one of those patterns. Use a glob tester tool if you are unsure how the pattern resolves.

For dynamic class names, search your source code for partial class name strings. If you find 'text-' + variable or template literals like text-${variable}-500, those are the culprits. The solution is always to ensure the full class name appears as a complete string somewhere — either in the component file, a constants file, or in the safelist array in tailwind.config.js.

For missing content paths: open tailwind.config.js and add the directory of the affected file to the content array. Use a glob pattern that covers the whole directory: './pages/**/*.{js,jsx,ts,tsx}'. Restart the dev server after changing the config — Tailwind does not always detect config changes in watch mode.

For dynamic class names: refactor the component to use a lookup object where keys map to complete class name strings. Every key in the object should be a complete Tailwind class, not a partial. Alternatively, add the specific classes to the safelist array in tailwind.config.js: safelist: ['bg-green-100', 'text-green-700', 'bg-red-100', 'text-red-700']. The safelist forces those classes to be generated regardless of whether they appear in source files.

For @apply not working: ensure the CSS file containing @apply is processed by PostCSS with the Tailwind plugin. The @apply rule only works in PostCSS-processed files — it does not work in inline styles or in CSS-in-JS solutions. Also check that the utility you are trying to @apply is in the utilities layer; base and component layer utilities may require different syntax.

For dark mode not working: check your tailwind.config.js for darkMode: 'class'. This setting requires a dark class on the html element (not body) to activate dark mode styles. If your theme toggle adds the class to body, move it to document.documentElement. If you want dark mode to follow the OS preference automatically, change to darkMode: 'media' — no class toggling required.

When diagnosing which classes would be generated without committing to a full build, run npx tailwindcss --content './src/**/*.tsx' --dry-run in your terminal. This command scans the specified content glob and prints a preview of the CSS that would be generated, letting you verify that the classes you expect are detected before running a complete production build.

Safelisting supports patterns as well as explicit strings. The safelist array in tailwind.config.js can include objects with a pattern property: { pattern: /bg-(red|green|blue)-(100|200|500)/ }. This generates all matching combinations without listing each one individually. Use patterns when you have a finite set of dynamic values that you can express as a regex.

Third-party components that pass className props can also cause missing classes. If a library component accepts a className prop and you pass Tailwind classes to it, those classes should be detected normally by the scanner as long as the class names appear as literal strings in your source. The issue arises when the library generates class names internally using concatenation — in that case, use the safelist or a custom CSS override.

Storybook and testing environments often run Tailwind separately from the main application. If your stories or test files are not included in the content array, Tailwind classes used in those files will not be generated for the Storybook build. Add .storybook/**/*.{js,jsx,ts,tsx} and stories/**/*.stories.{js,jsx,ts,tsx} to your content paths, or configure Storybook to use the same Tailwind CSS entry point as your app.

In Tailwind v4, the CSS entry file uses @import 'tailwindcss'; rather than the three @tailwind directives. If you are on v4 and still using @tailwind base; @tailwind components; @tailwind utilities;, those directives are silently ignored and your styles will not load at all. The migration guide at tailwindcss.com covers the v3-to-v4 changes in detail — it is worth reading fully before upgrading any production project confidently.

Forgetting to add @tailwind base; @tailwind components; @tailwind utilities; to the main CSS file is the most common setup mistake. These three directives inject Tailwind's reset, component layer, and utility layer respectively. Without them, even if Tailwind generates CSS, the file containing those utilities is never imported. In a Next.js project, this goes in globals.css; in a Vite project, it typically goes in main.css or index.css.

Using NEXT_PUBLIC_ prefix on secrets or API URLs is unrelated to Tailwind, but a related mistake is wrapping Tailwind class names in template literals unnecessarily. Writing className={`flex items-center`} when you mean className="flex items-center" is fine — both work. But writing className={`flex ${isActive ? 'bg-blue-500' : 'bg-gray-500'}`} is also fine, because both bg-blue-500 and bg-gray-500 appear as complete strings. The mistake is breaking the class name across an interpolation boundary.

Overriding Tailwind utilities with custom CSS using the same selector often fails because Tailwind utilities are imported last in the CSS cascade and have higher source order than earlier custom rules. If you need to override a Tailwind utility, use a more specific selector, apply the @layer directive to control where your custom styles land, or simply add an additional class to the element with higher specificity.

Plugins in tailwind.config.js that are listed but not installed as npm packages cause the entire Tailwind build to fail silently or with a cryptic module not found error. Always verify that require('@tailwindcss/forms') and require('@tailwindcss/typography') are listed in your package.json dependencies and installed with npm install before adding them to the plugins array.

Configure your content paths conservatively to cover every location that could contain Tailwind classes. Include not just your main component directories but also any scripts, utilities, or config files that might pass class names as strings. Over-inclusive content paths add a small amount of build time but prevent the frustrating experience of classes working locally and disappearing in production.

Adopt the convention of always writing complete Tailwind class names in source code. Document this in your team's contribution guide: never construct class names using string concatenation or template literal interpolation. Instead, use a lookup object or an array of conditional class names where each entry is a complete, static string. Libraries like clsx and classnames make this pattern ergonomic while keeping all class names as detectable string literals.

For design systems or component libraries distributed as npm packages, enable the component package scanning option or publish a prebuilt CSS file rather than relying on the consuming application to scan your package. Tailwind v4 introduced better support for pre-built package CSS, but in v3, consuming apps need to add your package's files to their content array: './node_modules/@yourcompany/ui/**/*.js'.

Run your production build locally before deploying when you make significant changes to the component tree or add new Tailwind classes. Production builds apply all optimizations including content scanning, which can reveal class coverage gaps that are masked in development mode. A simple npm run build followed by a visual inspection of the production build in the browser catches most class-stripping issues before they reach users.