How to Make a Safelist in Tailwind v4.1+

August 24, 2025

This article was updated on September 7th, 2025 to include more information.

Tailwind v4.1 introduced an easy way to handle safelisting CSS classes. Let’s take a look at that!

It’s as simple as using @source inline(), and listing the class you want to whitelist.

For example, if Tailwind can’t find the text-shadow-md class in our source files, but you still need it to generate in our CSS, you can do this:

@source inline("text-shadow-md");

I feel like the Tailwind docs on this don’t do a great job of explaining how all of this works, as it’s very easy to misunderstand.

Safelisting Multiple Classes

When safelisting, we can either use separate statements or combine using spaces. You may want to consider separate statements sometimes for readability.

@source inline("text-shadow-md");
@source inline("float-left");
@source inline("text-shadow-md float-left");

Note that separating with spaces works with the more advanced examples below as well.

Safelisting Multiple Utilities

We can generate multiple utilities at once using curly braces {}.

@source inline("text-shadow-{sm,md,lg}");

For classes that involve numbers, we can do ranges.

@source inline("p-{2..10..2}");

This takes 3 arguments: the starting number, the ending number, and what to increment by.

This will generate the classes p-2, p-4, p-6, p-8, and p-10.

You can also add additional values to be included by using commas. This generates the classes mentioned above, plus p-50 and p-100.

@source inline("p-{50,{2..10..2},100}");

This is pretty cool. You can combine variants together. In the example below, we’re safelisting both margin and padding classes, including various directions, between a number range of 0 - 100, all in one @source statement.

@source inline("{m,p}{x,y,t,b,l,r}-{0..100}");

Safelisting Multiple Variants

You can also generate variant classes. This will generate hover:text-shadow-md.

@source inline("{hover:}text-shadow-md");

If you want to generate both the normal and hover version, you can do that by adding a trailing comma.

@source inline("{hover:,}text-shadow-md");

You can also combine multiple variants. This will generate hover:float-left and focus:float-left.

@source inline("{hover:,focus:}float-left");

If you want to safelist the normal float-left as well, add the trailing comma.

@source inline("{hover:,focus:,}float-left");

Any variant you want, and you can combine these various concepts.

@source inline("{nth-of-type-3:,}p-{50,{2..10..2},100}");

Safelisting with Breakpoints

You can apply the same ideas to breakpoints.

@source inline("{sm:,md:,lg:,xl:,2xl:,}text-shadow-md");

Excluding Classes

This concept is basically the opposite of whitelisting classes. You can also blacklist classes. You can use @source not inline() to exclude CSS from being generated when they otherwise would be, and this will work with any of our examples above.

@source not inline("text-shadow-md");

I’m going to refrain from relisting every example above here with not inline(), but you get the idea.

Tailwind Source Files

I wanted to mention this, even though it seems obvious to me. You can avoid whitelisting by being sure Tailwind can read your classes in your source files.

For most projects, your classes should be read automatically. If you need a specific folder that needs to be read that isn’t being read, you can tell Tailwind to read it.

You can include as many of these declarations as you need. The path is relative to your CSS file.

@source ("./src");
@source ("../../../app/templates");

You can also set the base path when you include Tailwind in your CSS.

@import "tailwindcss" source("./src");

You can also disable automatic detection altogether.

@import "tailwindcss" source(none);

You would then need to safelist everything you need.

If you’re having trouble getting your classes to be read, be sure you explicitly have the classes in your file and don’t generate them dynamically. Using a switch statement is a good approach.

let btnClass = "";


switch (status) {
  case "success":
    btnClass = "bg-green-500";
    break;
  case "error":
    btnClass = "bg-red-500";
    break;
  case "warning":
    btnClass = "bg-yellow-500";
    break;
  default:
    btnClass = "bg-gray-500";
    break;
}

Your classes won’t automatically be detected if you dynamically generate them. Do NOT do this unless you want to safelist them manually.

let btnClass = `bg-${status}-500`;

Conclusion

This concept is pretty confusing at first, especially given that Tailwind doesn’t document this very well. Although, once you get the hang of it, it’s awesome!

This article is a follow-up to my previous article, which was released before Tailwind v4.1 was released. It may still be helpful if you have a more advanced use case.

Back to Blog