[Feature Proposal] Provide Configuration as CSS Custom Properties

[dantodev]

I like to pick up the discussion from #1022. The idea of this issue was to replace theme with css custom properties. My proposal is to provide both alongside each other.

In fact it is already possible to use custom properties in the tailwind configuration manually like #260 described:

/* main.css */
:root {
  --colors-primary: red;
}

@tailwind base;
@tailwind components;
@tailwind utilities;

// tailwind.config.js
module.exports = {
  theme: {
    color: {
      primary: "var(--colors-primary)"
    }
  }
}:

But by manually using css custom properties, the usage of theme is not possible on compile time anymore because now the real value is only available on runtime. If tailwind would provide both css custom properties and theme this would be no problem. So having both css custom properties and theme is not redundant.

Implementing css custom properties the right way could even enable us to override variables on runtime without any build system needed. This could open awesome new opportunities for tailwind.

Sure this idea is not fully thought through. The browser support for css custom properties could be a problem, or the fact that changing variables on runtime will not effect cases where theme has been used on compile time. But maybe this idea is worth further consideration.

[nemrutco]

I am not sure if this will help but, I have been working on some idea on one of my project about smilar thing. I was looking a way to define my root colors from my color palette and dynamically create shades. I end up something like this:

Sass/CSS

//color palette
$orange : #FF6F5F;
$blue : #4B78AD;
$neutral :#666;

$colors: ('primary':$orange, 'secondary':$blue, 'neutral':$neutral);

@function force-hex($color) {
    @if type-of($color)=='color' {
        $hex: str-slice(ie-hex-str($color), 4);
        @return unquote("\##{$hex}");
    }

    @return $color;
}

:root {

    @each $name,
    $color in $colors {
        --color-#{$name}-lighter: #{force-hex(lighten($color,40%))};
        --color-#{$name}-light: #{force-hex(lighten($color,14%))};
        --color-#{$name}: #{$color};
        --color-#{$name}-dark: #{force-hex(darken($color,14%))};
        --color-#{$name}-darker: #{force-hex(darken($color,40%))};
    }
}

@tailwind base;

@tailwind components;

@tailwind utilities;

tailwind.config.js

module.exports = {
    theme: {
        colors: {
            white: '#fff',
            black: '#333',
            primary: {
                lighter: 'var(--color-primary-lighter)',
                light: 'var(--color-primary-light)',
                default: 'var(--color-primary)',
                dark: 'var(--color-primary-dark)',
                darker: 'var(--color-primary-darker)',
            },
            secondary: {
                lighter: 'var(--color-secondary-lighter)',
                light: 'var(--color-secondary-light)',
                default: 'var(--color-secondary)',
                dark: 'var(--color-secondary-dark)',
                darker: 'var(--color-secondary-darker)',
            },
            neutral: {
                lighter: 'var(--color-neutral-lighter)',
                light: 'var(--color-neutral-light)',
                default: 'var(--color-neutral)',
                dark: 'var(--color-neutral-dark)',
                darker: 'var(--color-neutral-darker)',
            },
        },
        extend: {

        },
    },
    variants: {},
    plugins: [],
}

Now i could use any of the color variation same way as tailwind provides.

<p class="text-primary-light">Hello World</p>

I was using sass because i would like to define only main colors and dynamically create the variations. BTW root colors requires hex or rgba colors as i experienced. So in my sass i convert my colors to HEX using force-hex function.

I think if tailwind references custom colors from root by default, overwriting will be easier without compile.

[dantodev]

This is exactly the workaround described in #260. This way you still have to define the custom properties on your own, its not happening automatically. I would like to have this behavior out of the box or atleast as a configuration I can enable in my tailwind.config.js.

[adamwathan]

@dantodev Can you show an example of what you'd actually want Tailwind to generate so I know I understand 100% what you're suggesting? Sometimes it's easier to just see the output you want instead of trying to piece it together from a description.

[nemrutco]

I think I have similar point with @dantodev. This might already exists in tailwind but i still would like to know if is it possible:

Let's say we want to define our color palette in our css using :root pseudo-class and ask tailwind to figure out what are the new colors or existing colors are given and generate all shades of those colors.

/*app.css*/
:root {
    --color-blue: #4267b2;
    --color-primary: #FF6F5F;
    --color-secondary: #4B78AD;
    --color-neutral : #666;
}

@tailwind base;

@tailwind components;

@tailwind utilities;

Is it possible without touching anything in tailwind.config file, but let tailwind automatically detect new colors from :root and generate all the 100 to 900 shades using tailwind default color generation pattern. (I am not sure if there is such an algorithm to generate color palettes like the one used in tailwind default colors

/*
* It would be great if tailwind could generate color palettes using a base color 
* and convert it to HSL like 500 to be the base color  and 100 lighter 900 darker.
*/
100: 'hsl(201, 100%, 96%)',
200: 'hsl(202, 81%, 86%)',
300: 'hsl(203, 82%, 76%)',
...
900: 'hsl(215, 41%, 28%)',

or is it possible to define them only in tailwind.config by adding something like "customBaseColors".

module.exports = {
    theme: {
        colors: {
            white: '#fff',
            black: '#333',
        },
       customBaseColors: {
            blue: '#4267b2',
            primary: '#FF6F5',
            secondary: '#4B78AD',
            neutral :  '#666',
       }
        extend: {

        },
    },
    variants: {},
    plugins: [],
}

BTW if any tailwind's default colors like "blue" defined in the examples, it will re-generate or overwrite it. :

and finaly as a result we get this:

/*
* Ignore the color codes they are all same.
* Consider like they are generated by the color algorithm from tailwild for each shade
*/
.text-blue {
  color: #FF6F5F;
}

.text-blue-100 {
  color: #FF6F5F;
}

.text-blue-200 {
  color: #FF6F5F;
}
...
...
.text-blue-900 {
  color: #FF6F5F;
}
...
.bg-blue-100 {
  color: #FF6F5F;
}
.bg-blue-200 {
  color: #FF6F5F;
}
...
...
.bg-blue-900 {
  color: #FF6F5F;
}
...
.text-primary {
  color: #FF6F5F;
}

.text-primary-100 {
  color: #FF6F5F;
}

.text-primary-200 {
  color: #FF6F5F;
}
...
...
.text-primary-900 {
  color: #FF6F5F;
}
...
.bg-primary-100 {
  color: #FF6F5F;
}
.bg-primary-200 {
  color: #FF6F5F;
}
...
...
.bg-primary-900 {
  color: #FF6F5F;
}
...
...
...

[nemrutco]

Just found out this:

A common question we get is "how do I generate the 100–900 shades of my own custom colors?".

Bad news: color is complicated and we've yet to find a tool that does a good job generating these sorts of color palettes. We picked all of Tailwind's default colors by hand, balancing them by eye. Sorry!

So, tailwind colors are defined by hand. Nothing dynamically generated, No any algorithm but there won't be any in future? I have seen some algorithms writen by java and C# but not sure if they will fit tailwind.

[hacknug]

Take a look at this https://javisperez.github.io/tailwindcolorshades/#/?blue=0000ff&tv=1

[nemrutco]

Take a look at this https://javisperez.github.io/tailwindcolorshades/#/?blue=0000ff&tv=1

yup, exactly what i need out of the box by tailwind.

[tobx]

My 2 cents regarding automatic pleasing looking color algorithms:

I think this is not possible or at least not without better models trained by humans (like with compressed audio).

Simply compare bg-green-500 (#48bb78):
https://javisperez.github.io/tailwindcolorshades/?chateau-green=48bb78

with Tailwind's theme:
https://tailwindcss.com/docs/customizing-colors#default-color-palette

Tailwind's colors look nice, the algorithm gets pretty ugly, just check the color distances between 500, 600 and 700.

I think many programmers (or at least me in the past) tend to think that colors generated by an algorithm are somehow correct, but I think this is wrong. They are not good, they are fast. Most people can choose better colors by eye.

Pick colors by eye whenever possible. You do not need all shades anyway. Tailwind gives a good starting point. Color is art :)

So I vote against this in order to improve Tailwind in other areas. Nothing against custom properties though, this would be great ;)

[tobx]

I think this is not possible or at least not without better models trained by humans (like with compressed audio).

Someone took that very serious:
https://tailwind.ink 😄

[dantodev]

To bring this issue back to its origin, imagine the following simplified configuration:

// tailwind.config.js
return {
  theme: {
    colors: { red: "#FF0000" },
    spacing: { xl: "3rem" }
  }
};

I would like tailwind to generate one of the following outputs:

Option 1: Only generate CSS custom properties from tailwind configuration. Still inject the configured values in the generated CSS.

// output
:root {
  --colors-red: #FF0000;
  --spacing-xl: 3rem;
}

.bg-red {
  background-color: #FF0000;
}

.p-xl {
  padding:  3rem;
}

Option 2: Not only generate the custom properties but also used them by var() in the generated CSS.

// output
:root {
  --colors-red: #FF0000;
  --spacing-xl: 3rem;
}

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

.p-xl {
  padding:  var(--spacing-xl);
}

The second option would result in an slightly bigger output but would have the benefit that you could override custom properties on runtime.

I don't know if it would be worth to do this for every single configuration key or just for colors, spacings an some other. Maybe this could be configured in the tailwind configuration. Something like this:

// tailwind.config.js
return {
  `customProperties: {
    mode: 'use', // "inject" => only inject custom properties in :root block
                 // "use" => use the properties in generated css
    exposedKeys: ['colors', 'spacings']
  }
};

[aarongeorge]

Bingo! Option 2 would be amazing.

It gives you the flexibility of being able to import the config file elsewhere in your code and having access to the static values. Saves you having to ask the DOM what the values are at runtime.

[PaulMorel]

Slightly related to this issue, while researching about this I stumbled upon this article about using CSS custom properties for optimizing CSS file size. Interesting way of doing this.
Would there be any benefit for Tailwind in generating its CSS in this manner?

[sebastiandedeyne]

I would love to be able to output CSS like @dantodev's option 2 mentioned in the above comment.

This new CSS property "output mode" could be a setting in tailwind.config.js similar to the important setting.

The only immediate downside I see with this approach is IE compatibility, so this behaviour should probably be opt-in for the foreseeable future.

Exposing CSS variables as a first class citizen would provide the following benefits:

Better in-browser development workflow

During development, you can tweak variables in the browser and they're immediately updated. For example, if I want to tweak a shade of blue in the browser, I can currently modify the text-blue-500 class, but that doesn't affect bg-blue-500, I need to make two modifications in devtools.

With custom properties, I'd only need to modify --color-blue-500 in :root and all usages are immediately updated

Modify values at runtime

If you're building a project that needs support for theming (e.g. different colors for different clients), CSS custom properties make it very easy to modify a theme without building a different style sheet. This can also be useful to tweak values based on dark mode or other environments.

Access theme properties in inline styles

This one is huge. When I'm writing a unique piece of CSS in an inline style, I need to hard-code color and spacing values. If all variables would be custom properties, they can be accessed from an HTML context.

<div 
  class="border border-blue-200" 
  style="box-shadow: 1px 1px 0 var(--color-white), 2px 2px 0 var(--color-blue-200)"
>

[aarongeorge]

@adamwathan with the clarification around this feature now done. What is your outlook on having this implemented as a feature?

[adamwathan]

Definitely I something I want to explore but no timeline for it right now. Likely something I'll spend more time on in the spring/summer when I am focused on new feature development again.

[aarongeorge]

Sounds good, thanks for getting back to us about this.

[liaoliaojun]

Here's an tailwindconfig transform to cssvars example:

https://github.com/liaoliaojun/cssvars-playground

[mrassili]

another use case for custom props is when you want to style a shadow dom element, you either need inline styles which tailwindcss doesn't provide to my knowledge OR use custom props which are accessible to the shadow dom

[yabdab]

This may be related, but what if I set a variable on which color family to use?

Like if I set primary = red, then I can use bg-primary-200, text-primary-500, border-primary-100, etc.... and it uses red, or blue, or whatever I set the primary color family to be. Is this possible?

[jonathanhefner]

Implementing css custom properties the right way could even enable us to override variables on runtime without any build system needed. This could open awesome new opportunities for tailwind.

This would be very useful when repackaging Tailwind the way e.g. tailwindcss-rails does.

I would guess part of the difficulty of this feature is choosing which configuration options to expose as CSS custom properties. Tailwind has many configuration options, and exposing all of them would bloat the CSS and possibly cause performance issues. There is a similar discussion for Bootstrap which might be helpful: twbs/bootstrap#32424.

I don't know if it would be worth to do this for every single configuration key or just for colors, spacings an some other. Maybe this could be configured in the tailwind configuration.

This would be a great first step. Later versions of Tailwind could decide what set of CSS custom properties to support by default, and those could be specified simply as a default configuration value.

[secondmanveran]

I didn't see this touched on above but I may have missed it. This would also be extraordinarily useful for component developers, and of course the end user's of these packages.

The problem we always see with Tailwind based component libraries is having to use a mountain of outside configuration to make the look and feel of components accessible to the designer of a given project.

For example look at VueTailwind in the Vue 2 space or the brand new PrimeVue Tailwind. Both great, but tons of configuration required if you want to apply your own look and feel.

With custom css props all of this become trivial in that the package creators can use custom css props to style the components right in the style block of the component, then when a project designer or developer wants to change it you simply redefine the prop. No need for all these configuration hoops to jump through.

Alex at Inkline uses this approach, (though sadly not using Tailwind) and it's brilliant, VitePress of course uses this approach as well.

Just something to ponder.