[v4] Improve the usage of CSS variables for dark/light mode #15083

IonianPlayboy · 2024-11-22T09:41:55Z

IonianPlayboy
Nov 22, 2024

Hello everyone, congratulations to the team for the launch of the v4 beta ! It's very exciting, and it looks amazing.

I have started playing with the new version with the 100% CSS config, and the only thing that did not convince so far is setting up dark/light mode colors with CSS variables.

Note

I am only talking about dark/light mode to keep this simple, but this could apply to any number of theme configured in your main CSS file.

The problem

`dark` variant usage

It's very easy to declare a custom dark variant to customize dark mode detection, as showed in the beta docs :

@variant dark (&:where(.dark, .dark *)); /* <body class="dark"> */ 
@variant dark (&:where([data-theme="dark"], [data-theme="dark"] *); /* <body data-theme="dark"> */

You can then use the dark variant anywhere in your app, and it will work just fine.

Even if at some point you need to change your dark mode detection strategy, or you create a lib that is consumed by other projects with a different dark mode logic, you just need to update/set one line of CSS to have all your app updated.

CSS variables usage

This is sadly not the case if you are working with CSS variables, instead of relying on the dark variant.

Your config would most likely look like something like this (see #14091 & #14095) :

:root {
  --text-fg: #000; 

  :where(.dark) {
    --text-fg: #fff;
  }
}

/* `inline` is necessary to make it work */
@theme inline {
  --color-fg: var(--text-fg);
}

On a local/personal project, this will work exactly like using the dark variant, and it is still pretty easy to change the detection logic by updating only one line of CSS.

However, this is much more problematic if you are publishing a lib. Your users can't override your dark mode detection logic without rewriting all the dark mode values themselves or with a hacky way to change the css file you provide.

Compared to v3

If I am being 100% honest, working with CSS variables in dark mode was not that much easier in v3. The main difference I see is that since v3 is based on a JS config file, libraries would most of the time read the darkModeconfig option to generate their colors in a way that would be compatible with the user's dark mode detection.

Since in v4 the JS config is optional, it is not a reliable technique anymore, and I don't see an alternative solution to solve this issue without forcing libraries to create their own, self-maintained custom config in JS to handle this.

Proposed solution

In my opinion, this is a pain point that is going to be encountered by a lot of users, since CSS variables for dark/light mode are very common when using design systems with design tokens. I find it worthwhile to improve the UX out of the box for this setup, and I believe that you should be able to stay 100% in your main CSS file to configure your dark mode to stay in the spirit of v4.

A potential solution could look like this :

/* Step 1: define your `dark` mode variant */
@variant dark (&:where(.dark, .dark *)); 

/* Step 2: define your color values, independently from the detection logic */
@variations {
  --text-fg: #000; /* this would be the default value */

  @dark {
    --text-fg: #fff; /* this would be the value when the dark mode variant selector matches the element */
  }
}

/* Step 3: define your theme colors as usual */
@theme inline {
  --color-fg: var(--text-fg);
}

This would compile to the same CSS as the example above, but the mode detection should be overridable by users of the lib by simply overriding the dark mode variant definition in their own CSS.

Now obviously this is most likely not the best syntax possible, but I think that the mental model of separating your color definitions from the theme/mode detection is sound.

minht11 · 2024-11-22T23:10:52Z

minht11
Nov 22, 2024

If you are supporting only relative newish browsers you can use light-dark css function.

--color-primary: light-dark(red, magenta);

and the only thing you need to change is color-scheme for colors to change. I am prototyping with this and this cleaned up a lot of code.

1 reply

IonianPlayboy Nov 23, 2024
Author

That's definitely a nicer way to work with CSS variables. If you are starting a new project in V4 where you have full ownership on the theme management, I think that's the best approach. Do you have any codebases where you mix this approach with the darkvariant ? I wonder how easy it would be to make them coexist in the same project.

I would love an alternative baked into Tailwind to support other dark mode detection strategies, and to let librairies detect the user's config. Otherwise you would be out of luck if you are using light-dark everywhere but your component library is expecting a .darkclass or a data attribute to toggle the dark/light mode. It sadly does not help if you want to support more than one theme too.

shavonn · 2024-12-20T18:54:11Z

shavonn
Dec 20, 2024

I was also curious about this support since you could set the dark color in the tailwind config file in 3. What I ended up doing that has worked in v4 is this:

@theme {
  --text-color: var(--color-zinc-950);
}
@layer base {
    .dark {
       --text-color: var(--color-white);
    }
}

I'm new to using Tailwind's more advanced features, so I don't know how it should be done, but this did work for me.

1 reply

pdas9647 Apr 2, 2025

Hey Shavonn, could you please help me? How are you using the text-color in the HTML elements?
Are you using "dark:..." or it is automatically adjusted?

sarojregmi200 · 2025-01-28T08:55:46Z

sarojregmi200
Jan 28, 2025

I don't know what is wrong but registering a custom-variant for dark class is not working.
Even the example shown in the docs is not working for custom dark mode selection.

Here is what i tired reading docs.
https://play.tailwindcss.com/NKoulCfDGM

Is there something wrong with the above implementation or there is some bug regarding this feature.

4 replies

gaojunran Feb 6, 2025

write @variant instead of @custom-variant works. And I don't know why, but should be fixed or clarified in the document.

maiconcarraro Feb 9, 2025

@gaojunran still the same, not working

wongjn Feb 9, 2025

Tailwind Play strips <html> and <body> elements. Changing it to a <div> works: https://play.tailwindcss.com/7XspA9mJzw

sarojregmi200 Feb 9, 2025

thank you @wongjn for pointing that out. Around 1-2 weeks earlier it was not working properly. I tried it locally as well.
It appears that it has been fixed and is working properly.
https://play.tailwindcss.com/qF3sOqlkjn?file=css

Now a little more complex selection with system theme support and custom override with class are working perfectly.
And both @custom-variant and @variant appears to be working fine.

joshuabaker · 2025-02-27T17:23:02Z

joshuabaker
Feb 27, 2025

The light-dark() CSS function is a nice option.

Alternatively, we can just make use of bracket variable syntax.

@layer base {
  :root {
    --background: var(--color-stone-100);
    --foreground: var(--color-stone-800);
    @variant dark {
    --background: var(--color-stone-900);
    --foreground: var(--color-stone-200);
    }
  }
}

<div class="bg-(--background) text-(--foreground)">
  …
</div>

Playground: https://play.tailwindcss.com/IlolEC84Tm

I’d hoped that we could’ve just used @variant dark within @theme/@theme inline.

1 reply

TheoryOfNekomata Mar 3, 2025

Unfortunately the light-dark() function would only work when color-scheme is set to light dark.

Would have been nice if Tailwind tried to "hijack" light-dark() to creating its own variables. It wouldn't be confusing if the color-* theme variables had a special way of being resolved in CSS.

Something like

@theme {
  --color-background: light-dark(white, black);
  --color-foreground: light-dark(black, white);
}

would have compiled to

:root {
  --color-background--light: white;
  --color-background--dark: black;
  --color-foreground--light: black;
  --color-foreground--dark: white;
}

/* assuming "light" is the default variant */
:root {
  --color-background: var(--color-background--light);
  --color-foreground: var(--color-foreground--light);
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-background: var(--color-background--dark);
    --color-foreground: var(--color-foreground--dark);
  }
}

Of course this could have been extensible to other variants than light or dark, but the light-dark() function is a way to define different colors for those 2 variants.

kwiat1990 · 2025-03-27T10:47:11Z

kwiat1990
Mar 27, 2025

For some reason using this approach:

:root {
  --text-fg: #000; 

  :where(.dark) {
    --text-fg: #fff;
  }
}

/* `inline` is necessary to make it work */
@theme inline {
  --color-fg: var(--text-fg);
}

a value of the text-fg variable stays unchanged although the .dark class was added/removed. I ended up doing something like this but I would rather say it’s neither clean nor intuitive:

@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));

@layer base {
    :root {
        --current-mode: var(--color-black);

        @variant dark {
            --current-mode: var(--color-white);
        }
    }
}

@theme inline {
    --color-current-mode: var(--current-mode);
}

@theme {
    --shadow: 2px 2px 0 0 var(--color-current-mode); /* I wanted to have a color, which changes depending on current color theme */
}

1 reply

naymurdev Apr 5, 2025

thanks @kwiat1990
it works for me 🎉

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[v4] Improve the usage of CSS variables for dark/light mode #15083

{{title}}

Replies: 5 comments 8 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

Select a reply

[v4] Improve the usage of CSS variables for dark/light mode #15083

The problem

dark variant usage

CSS variables usage

Compared to v3

Proposed solution

Replies: 5 comments · 8 replies

IonianPlayboy Nov 23, 2024 Author

`dark` variant usage

Replies: 5 comments 8 replies

IonianPlayboy Nov 23, 2024
Author