@csstools/postcss-color-function

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.

README

PostCSS Color Function

npm install @csstools/postcss-color-function --save-dev

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(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);

PostCSS Color Function runs in all Node environments, with special instructions for:

• Node
• PostCSS CLI
• PostCSS Load Config
• Webpack
• Next.js
• Gulp
• Grunt

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(display-p3 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.

[!NOTE] 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);
}

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).