TailwindCSS Prefixing Breaks Custom Theme Variables in Utility Classes

[rashadmehtab]

What version of Tailwind CSS are you using?

v4.1.11

What build tool (or framework if it abstracts the build tool) are you using?

webpack

What version of Node.js are you using?

v20.18.3

What browser are you using?

Chrome

What operating system are you using?

Windows

Reproduction URL

https://play.tailwindcss.com/be7vc5mYw8?file=css

Describe your issue

When using @import "tailwindcss" prefix(tw);, custom theme variables (e.g., --btn-color) inside a utility class (e.g., .btn) don't resolve correctly. The background color doesn't apply, and using var(--btn-color) breaks due to the prefix. The theme() function is deprecated and doesn't work in this case.

Steps to Reproduce:

1. Define a custom theme variable --btn-color.
2. Create a utility class that references var(--btn-color).
3. Add prefix(tw) to the Tailwind setup.
4. Apply the class tw:btn to an element.

Expected Behavior:

The button background should be the custom theme color --btn-color (red).

Actual Behavior:

The background color doesn't apply, and var(--btn-color) doesn’t work with the prefixed class.

Suggested Fix:

Ensure custom theme variables work correctly with prefixed class names

[wongjn]

You could consider using --theme() instead of var(): https://play.tailwindcss.com/LAFtQ44yDY?file=css. --theme() should resolve theme tokens properly.

[rashadmehtab]

@wongjn

Thank you! That solved the issue — looks like it's not documented.

[Matheun]

@rashadmehtab What happens is as follows:

When setting a prefix, it gets applied to both the classes and the variables.
This means that all the variables inside the @theme inline {} are compiled like so --{prefix}-{variable}. This then results in tailwind not being able to find --btn-color since it is compiled as --tw-btn-color.

What might be the solution you are looking for, could be to split the @theme definition:
(do note that i haven't actually tested this)

// File: custom-theme.css
// In here you can define the variables you do not want to be affected by the prefix.
@theme inline {
  --btn-color: red;
}

// File: main.css
@import "tailwindcss" prefix(tw);
@import "./custom-theme.css" prefix();

@theme inline {
  --custom-variable-affected-by-prefix: red;
}

@utility btn {
  background-color: var(--btn-color);
  padding-inline: 0.5rem;
  padding-block: 0.3rem;
  border-radius: 4px;
  border: 1px solid gray;
}

Or you could simply use the variable name with the prefix and define custom variables in a :root for example.