What is @csstools/postcss-color-function?
@csstools/postcss-color-function is a PostCSS plugin that allows you to use color-modifying functions within your CSS. This can be particularly useful for dynamically adjusting colors, such as lightening or darkening a base color, or mixing colors together.
What are @csstools/postcss-color-function's main functionalities?
Lighten a color
This feature allows you to lighten a color by a specified percentage. In this example, the background color is lightened by 20%.
body { background-color: color(#000000 lightness(+20%)); }
Darken a color
This feature allows you to darken a color by a specified percentage. In this example, the background color is darkened by 20%.
body { background-color: color(#ffffff lightness(-20%)); }
Mix two colors
This feature allows you to blend two colors together by a specified percentage. In this example, red and blue are blended together equally to create a purple background color.
body { background-color: color(#ff0000 blend(#0000ff 50%)); }
Adjust color saturation
This feature allows you to adjust the saturation of a color. In this example, the saturation of the red color is reduced by 50%.
body { background-color: color(#ff0000 saturation(-50%)); }
Other packages similar to @csstools/postcss-color-function
postcss-color-mod-function
postcss-color-mod-function is another PostCSS plugin that provides similar functionality for modifying colors in CSS. It supports a variety of color functions like lighten, darken, and blend, similar to @csstools/postcss-color-function. However, it is based on the CSS Color Module Level 4 specification, which may offer more standardized syntax.
postcss-color-function
postcss-color-function is an older PostCSS plugin that also allows you to use color-modifying functions in your CSS. While it offers similar features like lighten, darken, and mix, it is less actively maintained compared to @csstools/postcss-color-function.
polished
polished is a library of lightweight, easy-to-use functions for writing styles in JavaScript. It includes a variety of color manipulation functions such as lighten, darken, and mix. While it is not a PostCSS plugin, it can be used in conjunction with CSS-in-JS libraries like styled-components or emotion.
PostCSS Color Function
PostCSS Color Function lets you use the color
function in
CSS, following the CSS Color specification.
.color {
color: color(display-p3 0.64331 0.19245 0.16771);
}
:root {
--a-color: color(srgb 0.64331 0.19245 0.16771);
}
/* becomes */
.color {
color: rgb(179,35,35);
}
:root {
--a-color: rgb(164,49,43);
}
Usage
Add PostCSS Color Function to your project:
npm install postcss @csstools/postcss-color-function --save-dev
Use it as a PostCSS plugin:
const postcss = require('postcss');
const postcssColorFunction = require('@csstools/postcss-color-function');
postcss([
postcssColorFunction()
]).process(YOUR_CSS );
PostCSS Color Function runs in all Node environments, with special
instructions for:
Options
preserve
The preserve
option determines whether the original notation
is preserved. By default, it is not preserved.
postcssColorFunction({ preserve: true })
.color {
color: color(display-p3 0.64331 0.19245 0.16771);
}
:root {
--a-color: color(srgb 0.64331 0.19245 0.16771);
}
/* becomes */
.color {
color: rgb(179,35,35);
color: color(display-p3 0.64331 0.19245 0.16771);
}
:root {
--a-color: rgb(164,49,43);
}
@supports (color: color(srgb 0 0 0)) {
:root {
--a-color: color(srgb 0.64331 0.19245 0.16771);
}
}
enableProgressiveCustomProperties
The enableProgressiveCustomProperties
option determines whether the original notation
is wrapped with @supports
when used in Custom Properties. By default, it is enabled.
⚠️ We only recommend disabling this when you set preserve
to false
or if you bring your own fix for Custom Properties. See what the plugin does in its README.
postcssColorFunction({ enableProgressiveCustomProperties: false })
.color {
color: color(display-p3 0.64331 0.19245 0.16771);
}
:root {
--a-color: color(srgb 0.64331 0.19245 0.16771);
}
/* becomes */
.color {
color: rgb(179,35,35);
color: color(display-p3 0.64331 0.19245 0.16771);
}
:root {
--a-color: rgb(164,49,43);
--a-color: color(srgb 0.64331 0.19245 0.16771);
}
Custom properties do not fallback to the previous declaration
Supported Color Spaces
.color-spaces {
color: color(a98-rgb 0.803 0.484 0.944);
color: color(display-p3 0.8434 0.509 0.934);
color: color(prophoto-rgb 0.759 0.493 0.898);
color: color(rec2020 0.772 0.491 0.920);
color: color(srgb 0.897 0.488 0.959);
color: color(srgb-linear 0.783 0.203 0.910);
color: color(xyz 0.560 0.377 0.904);
color: color(xyz-d50 0.550 0.375 0.680);
color: color(xyz-d65 0.560 0.377 0.904);
}
Out of gamut colors
Depending on the browser implementation out of gamut colors may be clipped, resulting in a different color.
Fallback values generated by PostCSS Color Function are always mapped to a close alternative in sRGB.
When setting preserve
to true
the original values will be used by some browsers and these may be clipped.
Certain browsers will have an incorrect color if this occurs.
If the plugin detects out of gamut colors it will emit a warning :
"color(srgb-linear -0.01656 0.23079 0.25298)" is out of gamut for "srgb-linear". When "preserve: true" is set this will lead to unexpected results in some browsers.
To resolve this warning pick a larger color space when declaring the original value.
Copyright : color conversions
This software or document includes material copied from or derived from https://github.com/w3c/csswg-drafts/tree/main/css-color-4. Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang).