How to use Tailwinds `safelist` to handle dynamic classes

• 1. Understanding PurgeCSS in Tailwind CSS
• 2. Introducing Safelist
• 3. Configuring Safelist in tailwind.config.js
• 4. More advanced configurations
• 5. Safelist Examples and Use Cases
• 6. Best Practices for Safelisting
• Summary

Tailwind CSS is a popular utility-first CSS framework that allows developers to create custom designs quickly and efficiently. By default, Tailwind CSS generates a wide range of utility classes, which can lead to large file sizes. To address this issue, Tailwind CSS comes with a built-in feature called PurgeCSS that removes unused styles from the production build, making the final CSS file smaller and more performant. However, this automatic removal may sometimes cause issues when certain styles are used dynamically or conditionally in your application. In this article, we'll dive deep into the safelist feature in Tailwind CSS, learn how to whitelist specific styles, and explore various scenarios where using safelist can be helpful.

¶1. Understanding PurgeCSS in Tailwind CSS

PurgeCSS is a powerful tool that scans your project files for any class names used and removes the unused ones from the final CSS file. This significantly reduces the size of the generated CSS, making your application load faster.

By default, Tailwind CSS includes PurgeCSS configuration that scans your HTML, JavaScript, and Vue files for any class names. You can easily tweak what files are picked up within the content array of the config file.

In some situations, you might need to prevent specific styles from being removed, even if they're not detected in your files. This is where the safelist feature comes into play.

¶2. Introducing Safelist

Safelist is a feature in Tailwind CSS that allows you to whitelist certain styles so they don't get removed during the purging process. This is particularly useful when you have dynamic class names generated through JavaScript or applied based on user interaction. Another very common use-case for safelist is when colors or styles are driven from a CMS or backend framework. One such example might be a system that allows a website admin to edit the color of a category in a CMS, which in turn changes the color of the nav items for that category. Tailwind won't see the actual class name as the file will contain server-side code that outputs the color.

By adding these class names to the safelist, you ensure that they will always be included in your final CSS file, regardless of whether PurgeCSS can find them in your project files or not.

¶3. Configuring Safelist in tailwind.config.js

To configure the safelist in your Tailwind CSS project, you need to modify the tailwind.config.js file. The safelist is an array of class names that you want to keep in your final CSS file, even if they're not found in your project files. Here's an example of how to add class names to the safelist:

// tailwind.config.js
module.exports = {
  content: [
    // your content files here
  ],
  safelist: [
    'bg-red-500', 
    'text-white', 
    'hover:bg-red-700'
  ],  
  // other configurations
};

In this example, the bg-red-500, text-white, and hover:bg-red-700 classes are added to the safelist. These classes will always be included in your final CSS file, even if PurgeCSS doesn't find them in your project files.

¶4. More advanced configurations

If you have a lot of classes to manage within safelist, perhaps due to multiple colors and the need to support variants/modifiers such as :hover, :focus, :active and dark: then it can quickly become very challenging to manage these within safelist. The list will become huge very quickly.

That's where patterns come in. Tailwind support regex within the safelist:

safelist: [
  {
    pattern: /from-(blue|green|indigo|pink|orange|rose)-200/
  },
  {
    pattern: /to-(blue|green|indigo|pink|orange|rose)-100/,
  },
],

With these 2 entries we are effectively adding 12 classes. from-{color}-200 and to-{color}-100, where {color} is all of the colors in the list. It makes it much easier to manage the lists. Remember that tailwind.config.js is just a JavaScript file, so you can manage variables at the top of the file if you're managing lists of colors that are repeated heavily.

It's also possible to define variants for everything within the list without needing to explicitly list them in regex:

safelist: [
  {
    pattern: /text-(blue|green|indigo|pink|orange|rose)-(600|400)/,
    variants: ['hover'],
  },
  {
    pattern: /from-(blue|green|indigo|pink|orange|rose)-200/
  },
  {
    pattern: /to-(blue|green|indigo|pink|orange|rose)-100/,
  },
],

¶5. Safelist Examples and Use Cases

There are several scenarios where using the safelist feature can be helpful:

Dynamic class names: If you're generating class names dynamically based on some data or user input, PurgeCSS may not detect these classes and remove them from the final CSS file. By adding these dynamic classes to the safelist, you can ensure they're always available in your application.

// Example of a dynamic class name based on user input
const userInput = 'success'; // This value might come from an API or user input
const alertClass = `alert-${userInput}`;

// Generated class name: 'alert-success'

In this example, the alertClass variable generates a class name based on user input or data from an API. Since PurgeCSS can't detect this dynamic class name, you should add it to the safelist in your tailwind.config.js file.

Conditional styles: If you have styles that only apply under specific conditions, such as a dark mode or a mobile view, you can use the safelist to ensure those styles are always included in your final CSS file.

// Example of a conditional style based on a media query
@media (max-width: 767px) {
  .hidden-mobile {
    display: none;
  }
}

In this example, the hidden-mobile class is only applied when the viewport width is less than 768 pixels. Since this class might not be detected by PurgeCSS, you should add it to the safelist in your tailwind.config.js file.

¶6. Best Practices for Safelisting

When using the safelist feature in Tailwind CSS, keep the following best practices in mind:

• Only add classes to the safelist that are truly necessary. Adding too many classes can bloat your final CSS file and negate the benefits of PurgeCSS.
• If you have many dynamic class names or a complex application, consider using a function or regular expression to generate the safelist array. This can help keep your configuration cleaner and more maintainable.
• Test your production build to ensure that all required styles are included. This can help you catch any issues early on and avoid surprises when deploying your application.

¶Summary

The safelist feature in Tailwind CSS provides a powerful way to whitelist specific styles and ensure they are included in your final CSS file, even if they are not detected by PurgeCSS. By understanding how to configure the safelist and use it effectively in various scenarios, you can make your Tailwind CSS projects more robust and maintainable. Remember to follow best practices when using the safelist to ensure your final CSS file remains lean and performant.

Feel free to look over the Tailwind Docs on Safelist usage.