Sujal
icon

How to Safelist Classes in Tailwind CSS V4

Learn how to safelist classes in Tailwind CSS v4 after the removal of the tailwind.config.js file. Discover the new method to manually define safelisted classes and ensure they are applied correctly in your project

thumbnail image
2 min
Posted by :Sujal
Published on
Updated on

With the release of Tailwind CSS v4, some major changes have been introduced. One of the most significant changes is the removal of the tailwind.config.js file. Now, all configurations are directly managed within the global CSS file.

Another big change is the removal of the safelist class pattern from the Tailwind config. Previously, in Tailwind CSS v3, we could safelist classes dynamically using patterns inside the tailwind.config.js file. However, in Tailwind CSS v4, this approach no longer works.

Issue: Conditional Classes Not Applying

If you are applying Tailwind CSS classes conditionally, like in the following example:

JavaScript
Copy
import RichText from "../notion-inline-blocks/rich-text";
import cn from "../utils/class-merge";
import MentionPreviewRender from "../utils/notion-blocks/mention-preview/mention-preview-render";

export default function Paragraph({ block }) {
  return (
    <>
      <p
        className={cn(
          "my-[0.0625rem] min-h-[1.875rem] px-0.5 py-[0.1875rem] text-[1rem] leading-normal font-normal [word-break:_break-word] whitespace-pre-wrap first:mt-0.5 last:mb-0",
          block.paragraph.color !== "default" &&
            block.paragraph.color !== "default_background" &&
            (block.paragraph.color.includes("background")
              ? `bg-notion-${block.paragraph.color}`
              : `text-notion-${block.paragraph.color}_color`),
        )}
      >
        <RichText text={block.paragraph.rich_text} />
      </p>
      <MentionPreviewRender text={block.paragraph.rich_text} />
    </>
  );
}

Tailwind CSS will not apply the dynamically generated classes because it doesn’t know in advance which classes will be used.

Solution: Using a Safelist File

In Tailwind CSS v3, we used the safelist option inside the tailwind.config.js file to explicitly tell Tailwind which classes to keep during build. Since Tailwind CSS v4 no longer supports this, we need a new approach.

How to Safelist Classes in Tailwind CSS v4

To manually safelist classes, create a safelist-tailwindcss.txt file and define all the necessary classes inside it, like this:

Plain Text
Copy

md:grid-cols-1
md:grid-cols-2
md:grid-cols-3
md:grid-cols-4
md:grid-cols-5

----- rich text colors -----

text-notion-default_color
text-notion-blue_color
text-notion-brown_color
text-notion-gray_color
text-notion-green_color
text-notion-orange_color
text-notion-pink_color
text-notion-purple_color
text-notion-red_color
text-notion-yellow_color
text-notion-code_color


----- rich text background -----

bg-notion-default_background
bg-notion-blue_background
bg-notion-brown_background
bg-notion-gray_background
bg-notion-green_background
bg-notion-orange_background
bg-notion-pink_background
bg-notion-purple_background
bg-notion-red_background
bg-notion-yellow_background
bg-notion-code_background


----- callout background -----

bg-notion-callout-blue_background
bg-notion-callout-brown_background
bg-notion-callout-gray_background
bg-notion-callout-green_background
bg-notion-callout-orange_background
bg-notion-callout-pink_background
bg-notion-callout-purple_background
bg-notion-callout-red_background
bg-notion-callout-yellow_background


----- select colors -----

text-notion-select-default_color
text-notion-select-blue_color
text-notion-select-brown_color
text-notion-select-gray_color
text-notion-select-green_color
text-notion-select-orange_color
text-notion-select-pink_color
text-notion-select-purple_color
text-notion-select-red_color
text-notion-select-yellow_color
text-notion-select-code_color

----- select background -----

bg-notion-select-default_background
bg-notion-select-blue_background
bg-notion-select-brown_background
bg-notion-select-gray_background
bg-notion-select-green_background
bg-notion-select-orange_background
bg-notion-select-pink_background
bg-notion-select-purple_background
bg-notion-select-red_background
bg-notion-select-yellow_background
bg-notion-select-code_background

Where to Store the Safelist File?

You can store this file in the styles folder or the root directory, depending on your project structure.

Plain Text
Copy
my-project/
│── public/
│── src/
│   ├── app/
│   ├── components/
│   ├── styles/          # ✅ Recommended: Store safelist file here
│   │   ├── global.css
│   │   ├── safelist-tailwindcss.txt  # ✅ Safelist file
│   ├── utils/
│── package.json
│── postcss.config.js
│── safelist-tailwindcss.txt  # ✅ Alternative: Store in root directory

How Does This Work?

During development or build time, Tailwind automatically scans the root folder and detects which classes are used. By adding them to the safelist file, you ensure that Tailwind keeps these classes in the final CSS output

For more information, check the official documentation

Detecting classes in source files - Core concepts

Understanding and customizing how Tailwind scans your source files.

Logo
https://tailwindcss.com/docs/detecting-classes-in-source-files
Thumbnail

Conclusion

Since Tailwind CSS v4 has removed the safelist option from the config file, we now need to manually define and store classes in a separate safelist-tailwindcss.txt file. This ensures that dynamically applied classes are recognized and included during the build process.

This approach allows you to conditionally apply classes in your components without worrying about Tailwind purging them. 🚀

🔗 Related Blogs

⚙️ See Handy Tools