0Pricing
Tailwind CSS Academy · Aula

Lista segura de classes dinâmicas

Use a opção safelist em tailwind.config.js para garantir que os nomes de classes construídos dinamicamente, que o JIT não consegue detectar estaticamente, sejam sempre incluídos.

Lista segura de classes dinâmicas é uma aula grátis de Tailwind CSS Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Tailwind CSS Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Tailwind CSS Academy inclui 4 aulas no total.

Partes desta aula ainda não foram traduzidas e aparecem em inglês.

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.

Perguntas Frequentes

A aula “Lista segura de classes dinâmicas” é grátis?

Sim — o texto completo de “Lista segura de classes dinâmicas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Tailwind CSS Academy, atualize para CoddyKit PRO. O curso de Tailwind CSS Academy inclui 4 aulas no total.

O que vou aprender em “Lista segura de classes dinâmicas”?

Use a opção safelist em tailwind.config.js para garantir que os nomes de classes construídos dinamicamente, que o JIT não consegue detectar estaticamente, sejam sempre incluídos. Você pratica Tailwind CSS Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Tailwind CSS Academy?

Nenhuma experiência prévia é necessária. Tailwind CSS Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Lista segura de classes dinâmicas”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Tailwind CSS Academy?

Sim. Cada aula de Tailwind CSS Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Como funciona o mecanismo JIT
  2. Lista segura de classes dinâmicas
  3. Analisando e reduzindo o tamanho do pacote
  4. Valores arbitrários e seus custos
← Voltar para Tailwind CSS Academy