TailwindCSS is an amazing CSS utility library. It's pretty straightforward to set up, but there are a few common problems that arise from basic errors. Styles aren't applying. Styles were applying but don't anymore. Only some styles are applying. The solutions are almost always the same, so if you're finding that Tailwind just flat out doesn't seem to be working, here's what to do.
NB - This guide is for Tailwind v3. Tailwind is now on v4 and has several fundamental changes that render many of the issues below obsolete. Check which version you're using before attempting to apply the solutions here.
1. Check you've added the Tailwind directives to the CSS file
Whatever framework you're using (or even if you're not using one at all), your main CSS file needs to have the three basic Tailwind directives in place. Simply:
@tailwind base;
@tailwind components;
@tailwind utilities;
In some IDEs you might find that you get warnings for the these statements. This is simply because they are not valid CSS - they instead work with PostCSS. You can safely ignore the warnings, or if you're one of those people that just hates wiggly lines, set the file type in your IDE to PostCSS.
2. Check you're importing or linking your CSS file
Once your directives are in place, make sure you're actually linking to or importing the relevant CSS file into your project, e.g.
<link rel="stylesheet" href="styles.css">
import '../css/globals.css'
The telltale for this issue is your page having no styling - for example, Tailwind resets the font-family to sans-serif, so if you're seeing Times New Roman, you're not linking your CSS file correctly.
If you're using the CLI, it's worth noting that the file names and paths used as examples in the Tailwind docs are just that - examples. You aren't required to use /src/input.css and /dist/output.css - all you need is an input CSS file with the three @tailwind directives, and an output CSS file where Tailwind will build the classes you use to. They can be called anything and be placed anywhere in your file structure.
3. Make sure your content array is correct
Tailwind works by scanning your files for recognised class names and patterns and then including them in the CSS file. The files it scans are defined in the content array in tailwind.config.js. If this is pointing to the wrong place, Tailwind won't pick up any classes.
A telltale that this is the problem is that the Tailwind default styles are applying (e.g. your text is sans-serif and you have no default page padding), but the Tailwind classes you're adding in your markup aren't applying.
Sometimes, you might find that Tailwind has been working, but now you're in a different file and only a few classes are working. What happens in this situation is that classes you have used in other files are already built in, and so if you use them in your new file, they will apply, but new classes won't.
An example content array for a Next.js project looks like this:
content: [
"./app/**/*.{js,ts,jsx,tsx}",
"./pages/**/*.{js,ts,jsx,tsx}",
"./components/**/*.{js,ts,jsx,tsx}",
// Or if using `src` directory:
"./src/**/*.{js,ts,jsx,tsx}",
],
This checks the app,pages, components, and src folders, plus any subfolders (denoted by the **) for any file with the js,ts,jsx, or tsx extensions containing classes recognised by Tailwind. If you create a folder outside this range, Tailwind won't scan it.
4. Check your build process is running
Tailwind needs to scan your markup and rebuild the CSS every time you change it. You'd be surprised at how many times people forget this fact. So, check your dev server is running if you're using a framework, or if you're using the CLI, be sure to run the build command with the --watch flag so the CSS will automatically rebuild.
npx tailwindcss -i src/input.css -o dist/output.css --watch
5. Check you're not concatenating class strings
Tailwind works by scanning the files defined in your content array at build time. Because of this, you can't use concatenated class names, e.g.
<div class={`bg-${bgColor}`}>...</div>
The rule of thumb is, if you can't do a text search in your IDE to find the class name, it won't work with Tailwind.
The Tailwind Docs have several strategies you can use to get around this.
6. Check you're not overriding the defaults
The Tailwind config allows you to add custom fonts, colours, and other things to your setup. Crucially, there is a slight difference in how this is done if you want to retain access to Tailwind's defaults. Here's an example:
theme: {
colors: {
brand: "#b4d455"
}
}
This will override all the standard Tailwind colours, even black and white. Instead, use an extend object:
theme: {
extend: {
colors: {
brand: "#b4d455"
}
}
}
This will add the custom colour to the theme, leaving you access to all the defaults. The example uses colours, but it applies to any custom value you add to your config.
Conclusion
These steps will fix 95% of Tailwind problems. If you're still having trouble, feel free to join us in the Discord and we'll be happy to help you out.
Top comments (7)
Appreciate the article, but unfortunately it did NOT resolve my issues with Tailwindcss in my Blazor-Server web app using .NET 9. The entire process seems "janky" and difficult to diagnose issues.
I went thru the above process after I made modifications to Styles.src.css and got everything to complete with output to Styles.css (npm run dev) without errors and the new CSS was recognized by VS Intellisense ... but the changes didn't actually work in my razor page?
And deployment to our server was even worse as many UI visuals were gone/changed significantly. We paid $799 for team license on Tailwind Labs (tailwind UI) which comes with ZERO support (called "self-serve") and I later discovered it's just honor system.
Unfortunately, this product was something I inherited from contractors and to be honest, I'm likely to undo all the tailwindcss aspect of our project as it's not useful without support. Reliance of volunteers in a discord forum (who do their best to help) but ultimately don't have knowledge to rectify some issues.
The fact this article exists is cause for concern. At some point I think we lost focus of what software development "tools" are supposed to do for us ... spending half a day trying to resolve something as simple as color change on text just because the app uses Tailwindcss is a red flag ... a task that take 10 seconds using Style="...".
I hear you and it must be frustrating to have issues with a tool you didn't implement in the first place. You say "the fact this article exists is cause for concern", when in reality the vast majority of issues this article addresses are down to fundamental user error (eg not importing the css file into the markup) or lack of user knowledge about how Tailwind, and to a certain extent modern web dev tools, works (eg not realising that you need to build your css file every time you make a change).
There's nothing inherently unstable or complicated about Tailwind - it's used in millions of projects without issue. But there will always be edge cases (and I would argue that Blazor and .NET are somewhat edge in the modern web dev world) where there will be problems. I find it odd that you had issues when deploying - by the time you're at that stage using the CLI, Tailwind has long done its job, and you're just working with a CSS file like any other.
I'm not affiliated with Tailwind Labs in any way so I can't comment on your issues with the UI package and support.
Importing of CSS was fine. No documentation existed for .NET 9 / Blazor-Server environment. I was on my own using trial and error and gather "bits" of knowledge from other sources (hard to find) and project template examples and trying to put something together that worked for .NET 9 / Blazor-Server and Telerik-Blazor suite.
If I had discovered that $799 license cost came was "self-service" (aka no support), I would have removed Tailwind dependency from our application and gone another route that does provide support (paid for).
For now, we're staying with a very specific version of Tailwind and will NOT be moving forward with it. For whatever reason the prior contractor implemented "parts" of Tailwind but NOT all of Tailwind and then modified it more leaving us with an incomplete implementation of Tailwind.
I've been developing applications for 40+ years, and nothing really changes. These "tools" aren't really learning from their past, they just keep repeating the same "it's too difficult" to integrate seamlessly so just write up partial instructions on how to do it manually for "some" environments. No one is really "hearing" a developer's frustration, most seem to be deflecting and/or calling "lack of user knowledge". We still have version problems, we still have a "package" system that fails, we still have to Google search to discover why something that should be simple had turned into a game "hunt for solution". This is not progress.
I think it's perhaps asking a little much for someone making an open source tool to provide detailed documentation for every possible system it might be used in conjunction with, especially if the user is going to do things like only partially implement it. It sounds to me like the lion's share of the problem rests with your predecessor wanting to use Tailwind without properly exploring whether it was suitable for your use-case.
I'll disagree, proof is in the number google search hits for developers having issues installing and using tailwind. "Open Source" yes and no, we paid $799 for a license for our development team. I do agree, it was clearly the wrong choice for a UI tool as there is little to no documentation to support Blazor/.NET 9.
Like I said, I've been doing software engineering for 4 decades and I think you are to comfortable with living in the fog of command lines and multiple steps. Overall, the cost of software engineering projects needs to come down, tools like Tailwind that don't support what you consider "edge case" only increases the cost of development. Doesn't matter if it's OpenSource or Payware, the implementation and support should be consistent or the tool becomes irrelevant over time (see them come and go all the time). Tailwind could be the "right tool" if it were less reliant on steps and command lines and had an intelligent installation process ...
bring up a console window
npx tailwindcss -i .\Styles\styles.src.css -o .\wwwroot\css\styles.css
npm run dev
verify tailwindcss/forms version (plugins)
verify tailwindcss/typography version (plugins)
verify postcss version
verify tailwindcss version
Defining module exports and plugins in the Tailwind.config.js for content
run more command lines to get the correct versions that work with each other ... etc. etc.
Modification to styles.src.css is the "partial" implementation I was talking about for prior developers. They selected what they believed is all they needed and nothing more (seems reasonable).
The process of updating tailwind versions even within the same major version (i.e 3.x) can and does result in a broken UI, leaving developers trying to figure out what changed and why it impacted the UI. Costly process.
It seems we look at development in very different ways. I'm the lead developer and I manage developers, and I don't want them wasting A LOT of time trying to figure why a Tailwind update didn't work as expected. The prior contractors that used Tailwind was done out of familiarity with Tailwind, which I was fine with (I don't micro-manage my developers and have an expectation of responsibility short and long term). Given I paid $799 for Tailwind, I had assumed it came with some level of support and polish, I was wrong, my error.
Visit to Discord and community forums was frankly pointless ... again all volunteers so no one really has any incentive to get involved in "edge cases". Shame Blazor/.NET 9 is considered edge case given it's far faster to develop web and mobile and now desktop apps that can run on iOS, MacOS, Windows, Linux etc.
Anyway, I appreciate your responses and hopefully my feedback is of use.
tailwindcss can be overridden by style tag in body
Any CSS can be overridden by a style tag.