Tailwind is installed but the utility classes do nothing
Utility classes such as text-3xl or bg-blue-600 have no effect in the browserShort 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.
Fix it fast
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/*.css2Match what you see, then jump to its fix
- 1
The CSS file starts with @tailwind base; @tailwind components; @tailwind utilities;The stylesheet still uses the v3 directivesFix - 2
Nothing in the page's stylesheet mentions TailwindThe plugin or the CSS import is missing from the buildFix - 3
Classes such as text-red-600 work as literals, but not as `text-${color}-600`Class names are built from pieces at run timeFix - 4
Classes 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
Custom colours or fonts from the old config file are missingThe theme still lives in a tailwind.config.jsFix
- 1
What does the error look like?
Utility classes such as text-3xl or bg-blue-600 have no effect in the browserTailwind 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.css2Fix
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 devConfirmed by tailwindcss.com
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 devConfirmed by tailwindcss.com
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={`[^`]*\${' src2Fix
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 devConfirmed by tailwindcss.com
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 .gitignore2Fix
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 devConfirmed by tailwindcss.com
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 devConfirmed by tailwindcss.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Back end
Vite reports that tailwindcss cannot be used directly as a PostCSS plugin
Internal server error: [postcss] It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin.
In Tailwind CSS v4 the PostCSS plugin moved out of the tailwindcss package.
3 causes, each with a fixWeb 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 fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb 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 fixWeb apps
TypeScript marks className as an error on React Native components
Property 'className' does not exist on type
React Native components have no className prop in their own types.
3 causes, each with a fixWeb apps
A shadcn/ui Dialog stays open after the form is submitted
Form submits and the data saves, but the modal remains on screen
A shadcn Dialog is a Radix dialog.
3 causes, each with a fix