Tailwind CSS Academy · Lesson

Safe-Listing Dynamic Classes

Use the safelist option in tailwind.config.js to ensure dynamically constructed class names that JIT cannot statically detect are always included.

Safe-Listing Dynamic Classes is a free Tailwind CSS Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Tailwind CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Safe-Listing Problem

JIT's static scan is a strength for most cases, but it creates a challenge when class names are determined at runtime — from a database, an API response, or a user's color preferences. These dynamically determined class names never appear as complete strings in your source files, so JIT does not generate them.

The safelist in tailwind.config.js is the official solution: you explicitly list classes (or patterns) that JIT must always generate, regardless of whether they appear in your template files.

Basic Safelist Configuration

Add a safelist array to your tailwind.config.js. List any complete class names that JIT cannot detect statically. JIT will always generate CSS for every class in this array, even if it does not find them in your content files.

This is the simplest form of safe-listing — individual class names. It works well for a small number of known dynamic classes.

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,ts}'],
  safelist: [
    'bg-red-500',
    'bg-green-500',
    'bg-blue-500',
    'bg-yellow-500',
    'text-white',
    'text-gray-900',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Pattern-Based Safelisting

For dynamic values across an entire color scale, listing every individual class is tedious. Instead, use a pattern object in the safelist that specifies a regex pattern. JIT will generate all classes matching the pattern.

For example, to generate all background colors for alert levels (red, green, yellow, blue) across shades 100 and 700, you can use a pattern that matches exactly those combinations.

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js}'],
  safelist: [
    // Generate all bg-* text-* combinations for status colors
    {
      pattern: /bg-(red|green|blue|yellow|purple)-(100|500|700)/,
    },
    {
      pattern: /text-(red|green|blue|yellow|purple)-(700|800|900)/,
    },
    {
      pattern: /border-(red|green|blue|yellow|purple)-(300|500)/,
    },
  ],
  theme: {
    extend: {},
  },
}

Generating Variants With Patterns

Pattern-based safelisting also supports generating variants alongside the base class. Add a variants array to the pattern object to include hover, focus, dark, and responsive variants.

This is essential when the dynamically determined class is used inside interactive elements. For example, a status badge that changes color based on a database field needs its hover state generated too if the badge is a clickable button.

// tailwind.config.js
module.exports = {
  safelist: [
    {
      pattern: /bg-(red|green|blue|yellow)-(100|200|500|600)/,
      variants: ['hover', 'focus', 'dark', 'dark:hover'],
    },
    {
      pattern: /text-(red|green|blue|yellow)-(600|700|800)/,
      variants: ['hover', 'dark'],
    },
  ],
}

When to Use Safelisting

The safelist should be a last resort, not a first instinct. Before safe-listing, consider these alternatives:

Map values to full class strings in a JavaScript object — the cleanest solution
Inline styles for truly arbitrary runtime values like user-chosen hex colors
CSS variables with a fixed Tailwind class that references the variable

Overusing the safelist defeats the purpose of JIT and can re-introduce the problem of large CSS files.

// Preferred: map values to complete class strings
const statusClasses = {
  success: 'bg-green-100 text-green-800 border-green-300',
  error:   'bg-red-100 text-red-800 border-red-300',
  warning: 'bg-yellow-100 text-yellow-800 border-yellow-300',
  info:    'bg-blue-100 text-blue-800 border-blue-300',
};

// Usage in template:
// class={statusClasses[status]}
// JIT detects all four strings statically — no safelist needed!

Inline Styles for Truly Dynamic Values

When a value is truly arbitrary at runtime — like a user's custom brand color stored in a database — inline styles are the right tool. Tailwind utilities map to fixed values on the design scale, while inline styles can accept any computed value.

Combine Tailwind for layout and structure with inline styles for the one truly dynamic value. This keeps 99% of your styling in Tailwind and reserves inline styles for the specific dynamic case.

<!-- User's custom brand color from database -->
<div
  class="px-6 py-4 rounded-xl font-semibold text-white"
  style="background-color: {{ user.brandColor }}">
  Custom Brand Header
</div>

<!-- The layout, padding, rounding, and text color all use Tailwind utilities -->
<!-- Only the dynamic database value uses inline style -->
<!-- This keeps the JIT stylesheet small and Tailwind responsible for design scale -->

<!-- CSS variable approach (also good):
<style> :root { --brand: {{ user.brandColor }}; } </style>
<div class="bg-[var(--brand)] px-6 py-4 rounded-xl text-white">...</div>
-->

CSS Variables as Dynamic Values

A powerful technique is to set a CSS variable to the dynamic value and reference it with Tailwind's arbitrary value syntax: bg-[var(--brand-color)]. The class string bg-[var(--brand-color)] is a complete static string that JIT can detect and generate.

The CSS variable itself is then updated dynamically via JavaScript or inline styles on a parent element, while the class stays fixed in your template.

<!-- Static class referencing a CSS variable -->
<div
  id="card"
  class="bg-[var(--card-bg)] text-[var(--card-text)] px-6 py-4 rounded-xl">
  Dynamically colored card
</div>

<script>
  // Update the CSS variable dynamically
  const card = document.getElementById('card');
  card.style.setProperty('--card-bg', '#1a1a2e');
  card.style.setProperty('--card-text', '#e0e0e0');

  // The class 'bg-[var(--card-bg)]' is a static string
  // JIT generates it because it appears literally in the HTML
</script>

Safelist in a Monorepo or Component Library

When building a component library that other projects will consume, classes in your library's components must be included in the consuming project's JIT scan. Include the library's source in the content array of the consumer's config, or use a preset that ships a safelist.

If the library ships compiled JavaScript (not source HTML), add the package path to the consumer's content glob, pointing to the compiled JS files that still contain the class strings as literal strings.

// Consumer project's tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{html,js,ts,tsx}',
    // Include the UI library's compiled files so JIT finds its classes
    './node_modules/@my-company/ui/**/*.{js,ts}',
  ],
  safelist: [
    // Or explicitly list classes the library uses dynamically
    {
      pattern: /bg-(blue|red|green|gray)-(50|100|500|600|700)/,
    },
  ],
}

Verifying the Safelist Works

After adding classes to the safelist, verify they are being generated by inspecting the compiled CSS output. Run npx tailwindcss -i input.css -o output.css and search the output file for one of the safelisted classes.

If the class is missing, double-check the regex pattern in the safelist (regex errors are silent). You can also temporarily add the class as a string to the safelist to confirm the configuration is being read at all.

# Build and verify
npx tailwindcss -i input.css -o output.css

# Check if safelisted class is in output:
grep 'bg-red-500' output.css
# Should print: .bg-red-500 { background-color: #ef4444; }

# If missing, test with direct string:
# safelist: ['bg-red-500'] -- if this works, your regex is wrong

# Regex debugging:
const pattern = /bg-(red|green)-(100|500)/;
console.log(pattern.test('bg-red-500')); // true
console.log(pattern.test('bg-red-600')); // false -- 600 not in pattern

Blocklist to Exclude Classes

The opposite of a safelist is a blocklist — classes you want to prevent from being generated even if JIT detects them in your templates. This is rarely needed but useful when you are overriding Tailwind classes with custom CSS and want to avoid specificity conflicts from the generated utilities.

Add a blocklist array to tailwind.config.js with class names to exclude. JIT will skip these even if found in content files.

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js}'],
  blocklist: [
    // Prevent these classes from being generated
    // (e.g., you have custom .container styles that conflict)
    'container',
    // Prevent a whole pattern:
    // blocklist does NOT support regex -- individual names only
  ],
  theme: {
    extend: {},
  },
}

Safelisting From External Data Sources

In headless CMS projects, blog platforms, or user-themeable apps, class names may come from a database or CMS content field. The safelist should cover the set of all possible values the CMS allows users to choose from.

Document the allowed class set, restrict CMS inputs to that set, and mirror the restriction in the safelist pattern. This ensures no class is used in content that is not generated in the stylesheet — a common bug in CMS-driven Tailwind projects.

// Allowed alert colors in your CMS:
// success, error, warning, info
// Tailwind classes for each stored in CMS: 'bg-green-100', 'bg-red-100', etc.

// tailwind.config.js safelist:
module.exports = {
  safelist: [
    // Exact list matching what CMS allows
    'bg-green-100', 'text-green-800', 'border-green-300',
    'bg-red-100', 'text-red-800', 'border-red-300',
    'bg-yellow-100', 'text-yellow-800', 'border-yellow-300',
    'bg-blue-100', 'text-blue-800', 'border-blue-300',
  ],
}

Quick Check

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

Lesson Recap

In this lesson you learned: the safelist in tailwind.config.js forces JIT to generate classes regardless of whether they appear in scanned content files; pattern objects with regex values generate entire sets of related classes efficiently; and the best alternatives to safelisting are mapping dynamic values to complete class strings in JS objects, using inline styles for truly arbitrary runtime values, or leveraging CSS variables referenced with Tailwind's arbitrary value syntax. Next up we analyze and reduce bundle size.

Frequently asked questions

Is the “Safe-Listing Dynamic Classes” lesson free?

Yes — the full text of “Safe-Listing Dynamic Classes” is free to read here on the web, and the Tailwind CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Tailwind CSS Academy course, upgrade to CoddyKit PRO.

What will I learn in “Safe-Listing Dynamic Classes”?

Use the safelist option in tailwind.config.js to ensure dynamically constructed class names that JIT cannot statically detect are always included. You practise Tailwind CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Tailwind CSS Academy?

No prior experience is required. Tailwind CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Safe-Listing Dynamic Classes” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Tailwind CSS Academy lesson?

Yes. Every Tailwind CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Tailwind CSS Academy