Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A custom Tailwind color does not apply to the element

Errorbg-brand-500 has no effect and the element stays transparent

Short answer

Tailwind only creates a color class when it finds the whole class name in your source, and in v4 only when the color is defined in the --color-* theme namespace. Dynamic names like bg-${color}-500, a variable set in :root, or a v3 tailwind.config.js that v4 never loads all leave the class empty.

  • Applies to Tailwind CSS 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the built CSS or the browser's styles panel and search for the class. If the rule exists, a stronger rule overrides it. If it does not exist, one of the causes below stopped it from being generated.

    grep -n "brand-500" dist/assets/*.css
  2. 2Match what you see, then jump to its fix

    1. 1The code has bg-${color}-500 or text-{{ x }}-600, and only some colors workThe class name is built from a string at runtimeFix
    2. 2The color is set in :root { --brand: ... } and bg-brand does nothingThe color is a plain CSS variable, not a theme valueFix
    3. 3The project was upgraded to v4, theme.extend.colors still sits in tailwind.config.js, and the custom classes vanishedA v3 tailwind.config.js defines the colors and v4 never loads itFix
    4. 4After adding --color-*: initial, classes like bg-red-500 stopped workingYour own color list replaced the default paletteFix

What does the error look like?

  • bg-brand-500 has no effect and the element stays transparent
  • text-primary works in one component but not in another

Cause 1 of 4

The class name is built from a string at runtime

1Check

Tailwind reads source files as plain text. It cannot evaluate string concatenation or interpolation, so a class that never appears in full in your code is never generated.

grep -rn --include=*.jsx --include=*.tsx "bg-\${\|text-\${" src

2Fix

Write the full class names and pick between them with a lookup object.

const colorVariants = {
  brand: "bg-brand-500 hover:bg-brand-600 text-white",
  danger: "bg-red-500 hover:bg-red-400 text-white",
};
return <button className={colorVariants[color]}>{children}</button>;

3Verify

Rebuild; both classes now appear in the built CSS.

npm run build && grep -c "brand-500" dist/assets/*.css

Confirmed by tailwindcss.com

Did this fix it?

Cause 2 of 4

The color is a plain CSS variable, not a theme value

1Check

The Tailwind theme docs say variables defined with :root are ordinary variables with no utility class. A utility exists only for variables inside @theme, in the --color-* namespace.

grep -rn "@theme\|:root" src --include=*.css

2Fix

Declare the color in @theme with the --color- prefix. The text after the prefix becomes the class suffix.

@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.72 0.11 178);
}

3Verify

Use bg-brand-500 on an element and reload.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

Cause 3 of 4

A v3 tailwind.config.js defines the colors and v4 never loads it

1Check

The upgrade guide says JavaScript config files are no longer detected automatically in v4, and the v3 @tailwind directives were replaced by an @import.

grep -rn "@tailwind\|@config\|@import \"tailwindcss\"" src --include=*.css

2Fix

Move the colors to @theme, or load the old file explicitly with @config.

@import "tailwindcss";
@config "../../tailwind.config.js";

3Verify

Rebuild and check the class in the built CSS.

npm run build

Confirmed by tailwindcss.com

Did this fix it?

Cause 4 of 4

Your own color list replaced the default palette

1Check

Setting the namespace to initial removes every default color utility, so only the colors you list afterwards exist.

grep -rn "--color-\*" src --include=*.css

2Fix

Delete the reset line if you want to add colors next to the defaults, or list every color you still need.

@theme {
  /* remove this line to keep the default palette */
  --color-*: initial;
  --color-midnight: #121063;
}

3Verify

Rebuild and use both a default and a custom color.

npm run build

Confirmed by tailwindcss.com

Did this fix it?

How do I stop it coming back?

  • Always write complete class names in source; keep variants in a lookup object.
  • Put design tokens meant for utilities in @theme, and keep plain variables for :root.
  • After a major upgrade, search the built CSS for one class from each custom color.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Web apps

Hydration failed after adding next-themes dark mode

Console reports a server and client mismatch on the html element

next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.

3 causes, each with a fix

Web apps

Next.js fails with Cannot find module 'tailwindcss'

Error: Cannot find module 'tailwindcss'

Next.js loads Tailwind through PostCSS, so the error means the package named in postcss.config is not installed where the build runs.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.