Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Tailwind is installed but the utility classes do nothing

ErrorUtility classes such as text-3xl or bg-blue-600 have no effect in the browser

Short answer

When classes have no effect, the stylesheet either lacks the v4 import line, is never loaded by the page, or the class name never appears as plain text in a scanned file. Check the CSS import first, then build class names in full, then register unscanned folders with @source.

  • Applies to Tailwind CSS 4, Vite, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the browser developer tools, inspect an element that should be styled, and see whether the class name matches any rule. No rule at all means the CSS was not built; a rule for some classes only means those names were not detected.

    grep -rn "tailwindcss" package.json src/*.css
  2. 2Match what you see, then jump to its fix

    1. 1The CSS file starts with @tailwind base; @tailwind components; @tailwind utilities;The stylesheet still uses the v3 directivesFix
    2. 2Nothing in the page's stylesheet mentions TailwindThe plugin or the CSS import is missing from the buildFix
    3. 3Classes such as text-red-600 work as literals, but not as `text-${color}-600`Class names are built from pieces at run timeFix
    4. 4Classes inside a UI library in node_modules, or a path listed in .gitignore, are missingThe classes live in a file Tailwind does not scanFix
    5. 5Custom colours or fonts from the old config file are missingThe theme still lives in a tailwind.config.jsFix

What does the error look like?

  • Utility classes such as text-3xl or bg-blue-600 have no effect in the browser
  • Tailwind classes work in some components but not in others

Cause 1 of 5

The stylesheet still uses the v3 directives

1Check

Version 4 imports Tailwind through a normal CSS import. The three directives belong to v3.

npm ls tailwindcss
head -5 src/index.css

2Fix

Replace the three lines with one import.

/* src/index.css */
@import "tailwindcss";

3Verify

Restart the dev server and look at the page again.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

Cause 2 of 5

The plugin or the CSS import is missing from the build

1Check

The Vite setup has a plugin entry and a CSS file, and the page has to load that CSS.

grep -n "tailwindcss" vite.config.*
grep -rn "index.css\|style.css" index.html src/main.*

2Fix

Install the Vite plugin, register it, and make sure your entry file loads the stylesheet that contains the import line.

npm install tailwindcss @tailwindcss/vite

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({ plugins: [tailwindcss()] })

3Verify

Restart the server; the browser now shows a rule for text-3xl.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

Cause 3 of 5

Class names are built from pieces at run time

1Check

Tailwind reads files as plain text and does not run your code, so an interpolated name never appears as a whole class.

grep -rn 'className={`[^`]*\${' src

2Fix

Write complete class names and choose between them with a lookup.

const colorVariants = {
  blue: "bg-blue-600 hover:bg-blue-500",
  red: "bg-red-600 hover:bg-red-500",
};
<button className={colorVariants[color]}>Save</button>

3Verify

Switch the prop in the browser and watch the colour change.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

Cause 4 of 5

The classes live in a file Tailwind does not scan

1Check

Tailwind skips files in .gitignore, node_modules, binary files and CSS files.

cat .gitignore

2Fix

Register the folder in your CSS with @source.

@import "tailwindcss";
@source "../node_modules/@acmecorp/ui-lib";

3Verify

Restart the dev server and inspect a class from that library.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

Cause 5 of 5

The theme still lives in a tailwind.config.js

1Check

In v4, JavaScript config files are no longer detected automatically.

ls tailwind.config.*

2Fix

Load the file from your CSS, or move the values into an @theme block.

@import "tailwindcss";
@config "../tailwind.config.js";

3Verify

Use one custom class and confirm it is styled.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

How do I stop it coming back?

  • Write whole class names in code; use lookup objects for variants.
  • Keep one CSS entry file that holds the Tailwind import and load it once in the app entry.
  • After a v3 to v4 move, run the official upgrade tool on a branch and review the diff.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

A custom Tailwind color does not apply to the element

text-primary works in one component but not in another

Tailwind only creates a color class when it finds the whole class name in your source, and in v4 only when the color is defined in the --color-* theme namespace.

4 causes, each with a fix

Web apps

Hydration failed after adding next-themes dark mode

Console reports a server and client mismatch on the html element

next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.