Why is theme() deprecated in v4? Is there an alternative? This function is worth its weight in gold for CSS calculations.

[dg291223]

Why is the theme() function in v4 deprecated? Using only CSS variables makes no sense to me with the use of Lightning CSS. Especially with regard to the mathematical functions of CSS.

One great thing about Lightning CSS is that it can simplify the mathematical functions of CSS. But unfortunately only if no CSS variables are used.

https://lightningcss.dev/transpilation.html#math-functions

Here is an example of a fluid spacing calculation with CSS variables:

CSS Configuration:

@import "tailwindcss";

@theme {
  --min-width-raw: 20;
  --max-width-raw: 96;
  --min-size-raw: 0.125;
  --max-size-raw: 0.25;
}

@utility var-test-px-* {
  padding-inline: clamp(
    calc(var(--min-size-raw) * --value(number) * 1rem),
    calc(
      (var(--min-size-raw) * --value(number) * 1rem) + 
      ((100vw - (var(--min-width-raw) * 1rem)) / (var(--max-width-raw) - var(--min-width-raw))) * 
      (var(--max-size-raw) - var(--min-size-raw)) * --value(number)
    ),
    calc(var(--max-size-raw) * --value(number) * 1rem)
  );
}

var-test-px-20 compiles to:

:root{
  --min-width-raw: 20;
  --max-width-raw: 96;
  --min-size-raw: .125;
  --max-size-raw: .25
}

.var-test-px-20 {
  padding-inline:clamp(calc(var(--min-size-raw)*20*1rem),calc((var(--min-size-raw)*20*1rem) + ((100vw - (var(--min-width-raw)*1rem))/(var(--max-width-raw) - var(--min-width-raw)))*(var(--max-size-raw) - var(--min-size-raw))*20),calc(var(--max-size-raw)*20*1rem))
}

Here is an example of a calculation of the fluid spacing with theme():

CSS Configuration:

@import "tailwindcss";

@theme reference {
  --min-width-raw: 20;
  --max-width-raw: 96;
  --min-size-raw: 0.125;
  --max-size-raw: 0.25;
}

@utility theme-test-px-* {
  padding-inline: clamp(
    calc(theme(min-size-raw) * --value(number) * 1rem),
    calc(
      (theme(min-size-raw) * --value(number) * 1rem) + 
      ((100vw - (theme(min-width-raw) * 1rem)) / (theme(max-width-raw) - theme(min-width-raw))) * 
      (theme(max-size-raw) - theme(min-size-raw)) * --value(number)
    ),
    calc(theme(max-size-raw) * --value(number) * 1rem)
  );
}

theme-test-px-20 compiles to:

.theme-test-px-20 {
  padding-inline:clamp(2.5rem,3.28947vw + 1.84211rem,5rem)
}

The difference is impressive, isn't it? The root variables are also not required and can therefore be omitted with ‘@theme reference{}’ in the final CSS file. If you still need the CSS variables, you can also create them again in the CSS configuration under ‘’@theme‘’.

And here is another example of the general spacing behaviour of Tailwind v4:

I also wonder why a CSS variable has to be used here.

Here is the compiled code for e.g. px-4:

.px-4 {
  padding-inline:calc(var(--spacing)*4)
}

And here is a customised version for e.g. px-4 with theme():

/* CSS Configuration */
@import "tailwindcss";

@theme reference {
  --spacing-theme: .25rem;
}

@utility theme-px-* {
  padding-inline: calc(theme(spacing-theme) * --value(number));
}

/* theme-px-4 compiles to: */
.theme-px-4 {
  padding-inline: 1rem
}

Why doesn't it work the same way? It's better than inserting the CSS variable every time. There is also no disadvantage because I still have access to a global spacing variable via the CSS configuration. For those who need the CSS variable, an optional function should be available.

What do you think?

[philipp-spiess]

Hey! For places where CSS variables don't work sense, we still have the theme function. You'd use it like var in that case: https://play.tailwindcss.com/IAstyKzGGN?file=css

[Dorian30]

It is deprecated though. I need it for inline variables in media queries. We don't write typical CSS, but we do need this for some design system primitive definitions.

 @media (max-width: --theme(--breakpoint-sm)) {
    ...
  }

CSS variables do not support this use case. Will you guys keep theme until there is an alternative to achieve things like this?

[Dorian30]

@philipp-spiess multiple libraries leverage theme to achieve what you can't with CSS variables

I'd reconsider deprecating this 🙏

[wongjn]

From what I can see there, you at least can replace theme() in the shown code with var(). Also, the spacing references can use --spacing(). This is syntactic sugar for calc(var(--spacing) * <number>):

export const root = cva({
  base: [
    "[--nav—item—py—offset:calc(var(--nav—item—py)*0.5*-1)]",
    "flex flex—col",
    "rounded—(--nav—radius)",
    "border border—zinc-200",
    "shadow—sm",
  ],
  variants: {
    density: {
      compact: [
        "[--nav—radius:var(--radius-lg)]",
        "[--nav—item—px:--spacing(3)]",
        "[--nav—item—py:--spacing(2)]",
      ],
      cozy: [
        "[--nav—radius:var(--radius-xl)]",
        "[--nav—item—px:--spacing(5)]",
        "[--nav—item—py:--spacing(4)]",
      ],
    },
  },
  defaultVariants: {
    density: "compact",
  },
});

[zecka]

You mention that theme() is deprecated in v4. Where is that documented?

I couldn't find any mention of deprecation in the docs, upgrade guide, or release notes.

Personally, I still see a few advantages to theme():

• guarantees that the token exists in the Tailwind theme
• avoids accidentally referencing CSS variables outside the design system
• abstracts the configured prefix
• improves autocomplete and validation
• makes theme token refactoring safer

Did the Tailwind team officially recommend moving away from theme()? If so, could you share the source?

EDIT:

Beyond autocomplete and validation, I think theme() has another interesting property: it preserves contextual variable resolution.

For example:

:root {
  --token: blue;
}

@theme {
  --foo: var(--token);
}

.theme-a {
  --token: red;
}

If we write:

.foo {
  color: theme(--foo);
}

the generated CSS is effectively:

.foo {
  color: var(--token);
}

As a result, --token is resolved in the context where .foo is rendered. When .foo is inside .theme-a, the text is red.

However, if we write:

.foo {
  color: var(--foo);
}

then --foo is typically emitted as:

:root {
  --foo: var(--token);
}

and the browser resolves --foo from its declaration context. In this example, the text remains blue.

So theme() is not just syntactic sugar over var(). It effectively inlines the resolved theme value into the generated CSS.

This can be useful when theme tokens are composed from other variables that may vary depending on context. In those cases, theme() and var()

https://play.tailwindcss.com/6SufIZUxY9

[wongjn]

While not talking about deprecation specifically, the upgrade guide recommends using native CSS var() where possible:

Since v4 includes CSS variables for all of your theme values, we recommend using those variables instead of the theme() function whenever possible:

 .my-class {
-  background-color: theme(colors.red.500);
+  background-color: var(--color-red-500);
 }