UT Utility Draft
Build Workflows

Tailwind Dynamic Class Names: Why Builds Miss Them

Utility Draft · Updated 2026-07-19 · 4 min read
Tailwind Dynamic Class Names: Why Builds Miss Them
tldrTailwind can miss dynamic class names when code assembles fragments such as `bg-${color}-500`, because source detection looks for complete class tokens rather than evaluating every runtime expression. Replace interpolation with a validated lookup whose values contain full literal classes, verify that the file is included in the installed project’s source detection, rebuild with the project’s actual command, and confirm the selector appears in generated CSS.
Contents

Tailwind needs complete class tokens in detectable source

Tailwind dynamic class names fail when source code constructs fragments such as bg-${color}-500 at runtime. Tailwind scans source as text and cannot reliably infer every finished token that a programming language might assemble. Map dynamic values to complete, literal class strings instead, then confirm the source path is detected by the installed build setup.

The debugging guides in build workflows begin with the token, not with random cache demolition.

See the difference between values and class fragments

This pattern hides the final utilities from static detection:

function Badge({ color }) {
  return <span className={`bg-${color}-500 text-${color}-950`}>...</span>
}

At runtime, the browser may receive a plausible class. During the build, however, the source contains fragments rather than complete tokens such as bg-blue-500. CSS for the assembled result may never be generated.

Use a lookup whose values contain complete classes:

const badgeClasses = {
  blue: "bg-blue-500 text-blue-950",
  amber: "bg-amber-500 text-amber-950",
}

function Badge({ color }) {
  return <span className={badgeClasses[color]}>...</span>
}

Validate color before lookup and provide an intentional fallback or error behavior. The mapping is both detectable and reviewable: every allowed visual choice appears in source.

Diagnose a missing class in five checks

1. Inspect the rendered token

Use browser tools to confirm the element received the class you expected. A typo, empty lookup, conditional branch, or component prop can fail before Tailwind enters the story.

2. Search the generated CSS

Confirm whether the selector exists in the built output. If it exists, investigate cascade, variant conditions, or invalid markup. If it does not, continue toward source detection.

3. Search source for the complete token

Use exact search. If only fragments exist, replace construction with complete strings. Do not assume the scanner evaluates JavaScript, template code, or a content database.

4. Verify the source location

Check the official documentation for how the installed Tailwind version detects source files and how the project’s integration supplies them. Monorepos, external packages, generated templates, unusual extensions, and ignored paths may require explicit handling.

5. Run the real build

Use the project’s documented command and inspect its output. Development and production pipelines can differ. Work on a branch and review configuration changes before deployment; a broad source rule can increase output or include files that were never intended as templates.

Do not turn user input into utility names

Mapping user-controlled values directly into class strings is unreliable and can create unreviewed presentation behavior. Validate input and translate it through a finite mapping of approved complete classes.

When a value is genuinely continuous—an arbitrary measured position, for example—a CSS custom property or inline style may represent the data more honestly than trying to manufacture limitless utility tokens. Review security and content policies for the framework and application context.

Keep variants complete too

Responsive and state variants must remain part of the literal token:

const layouts = {
  compact: "grid-cols-1 md:grid-cols-2",
  wide: "grid-cols-1 md:grid-cols-3 xl:grid-cols-4",
}

The responsive design guide explains how those variants cascade, and layout patterns keeps the base layout visible.

Treat configuration as the last scoped fix

Sometimes a class must originate outside ordinary source files. Follow the installed version’s official source-registration or explicit-inclusion mechanism rather than copying an option from an older tutorial. Tailwind’s configuration surface has changed across releases.

Before changing it, record the missing token, its true source, why a literal mapping is insufficient, and how the generated output will be tested. A fix should make a defined content source visible—not invite every file on the machine to the CSS build like an open-ended reunion.

FAQ

Why does Tailwind not generate my dynamic class?

The source may contain fragments rather than a complete token, or the file may not be included in source detection. Inspect the rendered class, search generated CSS, search source for the exact full token, and verify the installed version’s source configuration. Tailwind does not generally execute application code to discover every string that could exist at runtime.

Can I use template literals with Tailwind classes?

Yes when each possible Tailwind token still appears as a complete literal in detectable source. A template literal that concatenates utility fragments can hide the final token. Prefer a mapping from application values to complete class strings. Ordinary interpolation for non-class text is a separate issue; the important boundary is what the Tailwind source scanner can detect.

How should I map component props to Tailwind classes?

Validate the prop and map each allowed value to a complete, reviewed class string. Provide intentional fallback or error behavior for unknown values. This makes the generated possibilities visible to Tailwind, code review, and tests. Avoid placing unrestricted user input directly into class names, especially when a finite set of visual variants is what the component actually supports.

Should I add every missing Tailwind class to a safelist?

Do not begin with a broad inclusion rule. First determine whether the token can live as a complete literal mapping and whether the source file is detected correctly. When classes truly originate outside ordinary source, use the explicit inclusion mechanism documented for the installed Tailwind version and keep the scope finite, reviewed, and tested against generated output.

How do I check whether Tailwind generated a class?

Run the project’s documented build, then search the generated CSS for the expected escaped selector or inspect it through browser developer tools. First confirm the rendered element received the intended token. If the selector exists, investigate cascade and variant conditions; if it does not, inspect literal token detection, source paths, version-specific configuration, and build differences.