[v4] Custom variables in `@theme` directive not work as expected #15122

lkwr · 2024-11-22T19:42:38Z

lkwr
Nov 22, 2024

Hi,

How can I use CSS variables defined in a data-* selector in the @theme directive?
I expected this example to work, but unfortunately it does not.

CSS:

@import "tailwindcss";

[data-theme="dark"] {
  --theme-color-background: red;
  --theme-color-foreground: blue;
}

[data-theme="light"] {
  --theme-color-background: blue;
  --theme-color-foreground: red;
}

@theme {
  --color-background: var(--theme-color-background);
  --color-foreground: var(--theme-color-foreground);
}

HTML:

<div>
  <div data-theme="dark">
    <p class="bg-background p-4 text-foreground">Text</p>
  </div>
  <div data-theme="light">
    <p class="bg-background p-4 text-foreground">Text</p>
  </div>
</div>

(playground link)

I want to be able to change the theme based on the data attribute on every element on the html. With tailwind v3 everything works fine by using css variables in the tailwind.config.ts

Answered by wongjn

Nov 22, 2024

You'd want to use the inline tag with @theme: https://play.tailwindcss.com/nSlymBjv3E?file=css

This changes the CSS rules from:

.bg-background {
  background-color: var(--color-background);
}

To:

.bg-background {
  background-color: var(--theme-color-background);
}

Allowing your CSS variables to be resolved correctly.

View full answer

wongjn · 2024-11-22T19:48:18Z

wongjn
Nov 22, 2024
Collaborator

You'd want to use the inline tag with @theme: https://play.tailwindcss.com/nSlymBjv3E?file=css

This changes the CSS rules from:

.bg-background {
  background-color: var(--color-background);
}

To:

.bg-background {
  background-color: var(--theme-color-background);
}

Allowing your CSS variables to be resolved correctly.

1 reply

lkwr Nov 22, 2024
Author

Thank you so much! 👍🏼🚀

kelvin2200 · 2024-11-23T09:49:18Z

kelvin2200
Nov 23, 2024

@wongjn What does the inline keyword do, and why does it solve the problem above?

5 replies

wongjn Nov 23, 2024
Collaborator

See #14095 for details on the inline option.

How it fixes the problem

Without `inline`:

Tailwind compiles to something like:

:root {
  …
  --color-background: var(--theme-color-background);
}

[data-theme="dark"] {
  --theme-color-background: red;
  --theme-color-foreground: blue;
}

[data-theme="light"] {
  --theme-color-background: blue;
  --theme-color-foreground: red;
}

@layer utilities {
  .bg-background {
    background-color: var(--color-background);
  }
}

With the following HTML:

<html>
  <head>…</head>
  <body>
    <div>
      <div data-theme="dark">
        <p class="bg-background p-4 text-foreground">Text</p>
      </div>
      <div data-theme="light">
        <p class="bg-background p-4 text-foreground">Text</p>
      </div>
    </div>
  </body>
</html>

So if we look at the background-color resolution steps for bg-background:

var(--color-background) means look for a definition of --color-background on itself or DOM parents.
The browser finds it at <html> (from the :root rule).
--color-background has value of var(--theme-color-background). The browser again, looks for a definition of --theme-color-background on itself or DOM parents.
No definition is found. Invalid (?) value, so discard (?) or use default.

With `inline`:

:root {
  …
  --color-background: var(--theme-color-background);
}

[data-theme="dark"] {
  --theme-color-background: red;
  --theme-color-foreground: blue;
}

[data-theme="light"] {
  --theme-color-background: blue;
  --theme-color-foreground: red;
}

@layer utilities {
  .bg-background {
    background-color: var(--theme-color-background);
  }
}

(Same HTML)

The resolution steps for bg-background become:

var(--theme-color-background) means look for a definition of --theme-color-background on itself or DOM parents.
The browser finds it at <div data-theme="dark"> or <div data-theme="light"> from our custom CSS rules.
--theme-color-background has valid <color> value of red or blue respectively.
Browser uses the <color> value for background-color.

Comparison

Without `inline`	With `inline`
`background-color: var(--color-background)`	`background-color: var(--theme-color-background)`
Looks for `--color-background` definition	Looks for `--theme-color-background` definition
Finds definition at `:root`	Finds definition at `[data-theme="dark"]` or `[data-theme="light"]`
Resolves to `var(--theme-color-background)`	Resolves to `red` or `blue`
Looks for `--theme-color-background` definition
Not found, invalid value

kelvin2200 Nov 23, 2024

@wongjn thank you for the detailed explanation, but now my level of confusion went red :))
Either my understanding of how css variables are overriden (on a global, and selector level) is totally wrong, or this resolution you've explained happens at build time.

Because once you're in the scope of [data-theme="light"] or dark

--theme-color-background:...
/* and */
--theme-color-foreground:...

should already be overriden...

Meaning that --color-background: var(--theme-color-background);
should resolve to whatever [data-theme="dark"] or [data-theme="light"] specified.

Now, if you don't explicitly wrap <p class="bg-background/> in a [data-theme="dark"] parent, then yes, root values should persist.

Or... does the scenario you explained apply for when :root defaults for those variables are NOT defined at all initially?

wongjn Nov 23, 2024
Collaborator

In the scope of [data-theme="light"] or [data-theme="dark"], --theme-color-background and --theme-color-foreground are indeed defined. But without inline, the background-color is var(--color-background), so it looks for --color-background. It finds it in <html>/:root. We are no longer in the scope of [data-theme="light"] or [data-theme="dark"]. :root then tries to resolve --theme-color-background but it is not defined.

kelvin2200 Nov 23, 2024

Yeah, it doesn't make sense at first glance, but you're right. If one were to use [data-theme="light"] as a descendant of [data-theme="dark"], they can't both override the root value, except within their own scope. If my assumption were correct (which it isn't), then the [data-theme="light"] child would override the [data-theme="dark"] values, and they'd both end up light. Thank you and I'm sorry for the confusion

edda Apr 23, 2025

@wongjn Your detailed explanation above just saved me probably hours of debug time in my tw3 -> tw4 migration project. Thank you so much! This should be part of the official tw4 documentation for the inline option!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[v4] Custom variables in `@theme` directive not work as expected #15122

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 6 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

[v4] Custom variables in @theme directive not work as expected #15122

Uh oh!

lkwr Nov 22, 2024

Replies: 2 comments · 6 replies

Uh oh!

wongjn Nov 22, 2024 Collaborator

Uh oh!

lkwr Nov 22, 2024 Author

Uh oh!

kelvin2200 Nov 23, 2024

Uh oh!

Uh oh!

wongjn Nov 23, 2024 Collaborator

How it fixes the problem

Without inline:

With inline:

Comparison

Uh oh!

kelvin2200 Nov 23, 2024

Uh oh!

wongjn Nov 23, 2024 Collaborator

Uh oh!

kelvin2200 Nov 23, 2024

Uh oh!

edda Apr 23, 2025

[v4] Custom variables in `@theme` directive not work as expected #15122

lkwr
Nov 22, 2024

Replies: 2 comments 6 replies

wongjn
Nov 22, 2024
Collaborator

lkwr Nov 22, 2024
Author

kelvin2200
Nov 23, 2024

wongjn Nov 23, 2024
Collaborator

Without `inline`:

With `inline`:

wongjn Nov 23, 2024
Collaborator