DEV Community: Plain Sailing with Tailwind

Getting started with Tailwind v4

Plain Sailing with Tailwind — Tue, 04 Mar 2025 15:12:21 +0000

Tailwind v4 is here, and with it come a few fundamental changes. This guide will hopefully demystify installing and using Tailwind v4.

Installing

First off, you need to install Tailwind. How you do that will depend on whether or not you're using a framework, and if so, what framework it is.

Frameworks

If you're using a framework like Next, Nuxt, Sveltekit, Solid, and so on, then the Tailwind docs probably have a dedicated guide for you:

https://tailwindcss.com/docs/installation/framework-guides

If you're using something like React or Vue without a framework (ie Next or Nuxt), then your best approach is to use Vite. First scaffold a new Vite project with your JS framework of choice:

https://vite.dev/guide/#scaffolding-your-first-vite-project

Then follow the Tailwind docs for Vite integration:

https://tailwindcss.com/docs/installation/using-vite

If for some reason you want to use PostCSS, you should use Vite to scaffold your new project, then follow the PostCSS installation docs:

https://tailwindcss.com/docs/installation/using-postcss

No framework, just static HTML

Firstly, if you're developing static HTML websites the old fashioned way, I would highly, highly recommend switching to Astro now and joining us in the 21st Century. It's an excellent framework, produces no JS that you don't add yourself, and also makes using Tailwind properly much more viable.

If you just want to try Tailwind out with static files, then this is how to do it.

Make a new folder for your project, eg twtest.
In that folder, in a terminal, initiate a new npm project with npm init -y. You can skip this step if you're using pnpm, which you should be.
Run npm install tailwindcss @tailwindcss/cli .
Create a new index.html and input.css file.
In input.css enter @import tailwindcss; and save.
In your HTML file, add your HTML boilerplate (! in Vs Code), and then add the link to an output CSS file (which you haven't created, yet): e.g.

html<link href="./output.css" rel="stylesheet">
In your terminal, run

npx @tailwindcss/cli -i ./input.css -o ./output.css --watch
Add some test Tailwind to your HTML, e.g.

html<h1 class="text-4xl font-bold text-red-500">Hello World!</h1>

Open your HTML file in a browser and you should see a big, red Hello World!

Customising your theme

The major user-facing change in Tailwind v4 is that there is no longer a tailwind.config.js file with which to configure your theme and any other customisations. If you're following a video tutorial somewhere and they go to tailwind.config.js, that tutorial is now out of date.

Instead, all customisation is done in your CSS file (e.g. app.css, input.css, global.css, or whatever CSS file has @import "tailwindcss"; in it. Customisation is done mainly via CSS variables.

For example, to add a new colour, you would do the following:

@import "tailwindcss";

@theme {
  --color-brand: #b4d455;
}

This would make that colour available to any utility that uses colours, ie bg-brand, text-brand, and so on. The Tailwind docs have a complete guide to theme customisation:

https://tailwindcss.com/docs/theme

FAQs

My CSS file has squiggly lines and warnings, why?
This is purely a VS Code issue - it thinks you're using CSS, when in fact you're using special CSS, with custom directives. Install the official Tailwind extension, and then set your file language to TailwindCSS, and the squiggly lines will be banished.

Where's the content array?
V3 used a content array to find the files where Tailwind was being used. V4 has done away with this and now uses several clever methods to find your files automagically. For the most part this works well, however if you need to explicitly point Tailwind to a folder you can do so with the @source directive e.g.:

@source "./src/components/"

Where's the safelist function?
There isn't one, at least not 'built in' as it was in V3. Instead, you can simply add a file (e.g. safelist.txt) and add any classes you want to build in that file. Tailwind's automatic content detection will pick them up.

Where's the blocklist function?
Again, there isn't one. However, Tailwind's content detection makes use of the .gitignore file to help it ignore content, so you can just add your paths to the .gitignore file to prevent them being scanned.

Conclusion

This is a basic guide so I won't go into much further depth. 99% of questions can be answered with a simple search on the Tailwind Docs site at tailwindcss.com. If you can't find the answers there, hop on to the Tailwind Discord and we'll do our best to help.

Stacking elements with Tailwind CSS

Plain Sailing with Tailwind — Wed, 24 May 2023 08:44:40 +0000

Stacking elements on top of each other is a common pattern that we all use regularly. There are two main approaches to achieving this with Tailwind CSS. We'll use a typical hero section layout with a background, a gradient layer, and some text as an example.

1. Absolute positioning

Absolute positioning is the 'traditional' way to stack elements. It's very flexible, but can be a pain to make responsive, and centering elements can feel a little hacky.

Let's start with our background:

<div class="h-screen bg-slate-500 relative">

</div>

We make this our relative parent simply by adding the relative class.

Now let's add our gradient:

<div class="h-screen bg-slate-500 relative">
  <div class="bg-gradient-to-t from-slate-800 to-transparent absolute inset-0"></div>
</div>

This will give us a dark gradient effect from the bottom. We position it absolutely to fill the container using absolute inset-0.

Now for the text:

<div class="h-screen bg-slate-500 relative">
  <div class="bg-gradient-to-t from-slate-800 to-transparent absolute inset-0"></div>

  <h1 class="text-6xl text-white font-bold absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">Tailwind CSS</h1>
</div>

After the text styling, we give our text absolute to position it absolutely, then position it halfway in on both the X and Y axes with left-1/2 top-1/2. However, since the origin point for the text is the top left corner, this results in the text appearing off-center. To remedy this, we use -translate-x-1/2 -translate-y-1/2 to move the text left and up by half its own width and height.

Here it is in action

This is a long walk for a short glass of water. Luckily, with the advent of CSS Grid, we have a more elegant solution...

2. Stacking elements with Grid

As well as making... grids, CSS Grid also allows us to stack grid elements on top of each other. The properties that allow this, grid-template-areas and grid-area don't have utility classes in TailwindCSS, but that's not a problem thanks to v3's arbitrary classes feature.

Let's define our container again:

<div class="h-screen bg-slate-500 grid place-items-center [grid-template-areas:'stack']">

</div>

Here we set up a grid container with grid. place-items-center will ensure our text is automatically dead center on the screen without any translate shenanigans. The real magic is in our arbitrary class [grid-template-areas:'stack']. This sets up a single grid area called stack - you can call this whatever you like.

Now we can add our gradient:

<div class="h-screen bg-slate-500 grid place-items-center [grid-template-areas:'stack']">
  <div class="h-screen w-full bg-gradient-to-t from-slate-800 to-transparent [grid-area:stack]"></div>
</div>

Here we use another arbitrary class to tell the browser that this element belongs to the stack grid area defined in the parent.

And now for the text:

<div class="h-screen bg-slate-500 grid place-items-center [grid-template-areas:'stack']">
  <div class="h-screen w-full bg-gradient-to-t from-slate-800 to-transparent [grid-area:stack]"></div>

  <h1 class="text-6xl font-bold text-white [grid-area:stack]">Tailwind CSS</h1>
</div>

This element in particular is much cleaner - all we need to center it is the same arbitrary class as the gradient. place-items-center on the parent takes care of the rest!

Here it is in action

Tailwind CSS not working? It's probably this...

Plain Sailing with Tailwind — Sun, 12 Feb 2023 17:19:51 +0000

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.