1 | # PostCSS color-mod() Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]
|
---|
2 |
|
---|
3 | [![NPM Version][npm-img]][npm-url]
|
---|
4 | [![CSS Standard Status][css-img]][css-url]
|
---|
5 | [![Build Status][cli-img]][cli-url]
|
---|
6 | [![Support Chat][git-img]][git-url]
|
---|
7 |
|
---|
8 | [PostCSS color-mod() Function] lets you modify colors using the `color-mod()`
|
---|
9 | function in CSS, following the [CSS Color Module Level 4] specification.
|
---|
10 |
|
---|
11 | **`color-mod()` has been removed from the Color Module Level 4 specification.**
|
---|
12 |
|
---|
13 | ```pcss
|
---|
14 | :root {
|
---|
15 | --brand-red: color-mod(yellow blend(red 50%));
|
---|
16 | --brand-red-hsl: color-mod(yellow blend(red 50% hsl));
|
---|
17 | --brand-red-hwb: color-mod(yellow blend(red 50% hwb));
|
---|
18 | --brand-red-dark: color-mod(red blackness(20%));
|
---|
19 | }
|
---|
20 |
|
---|
21 | /* becomes */
|
---|
22 |
|
---|
23 | :root {
|
---|
24 | --brand-red: rgb(255, 127.5, 0);
|
---|
25 | --brand-red-hsl: rgb(255, 127.5, 255);
|
---|
26 | --brand-red-hwb: rgb(255, 127.5, 0);
|
---|
27 | --brand-red-dark: rgb(204, 0, 0);
|
---|
28 | }
|
---|
29 |
|
---|
30 | /* or, using stringifier(color) { return color.toString() } */
|
---|
31 |
|
---|
32 | :root {
|
---|
33 | --brand-red: rgb(100% 50% 0% / 100%);
|
---|
34 | --brand-red-hsl: hsl(30 100% 50% / 100%);
|
---|
35 | --brand-red-hwb: hwb(30 0% 0% / 100%);
|
---|
36 | --brand-red-dark: hwb(0 0% 20% / 100%);
|
---|
37 | }
|
---|
38 | ```
|
---|
39 |
|
---|
40 | ### Supported Colors
|
---|
41 |
|
---|
42 | The `color-mod()` function accepts `rgb()`, legacy comma-separated `rgb()`,
|
---|
43 | `rgba()`, `hsl()`, legacy comma-separated `hsl()`, `hsla()`, `hwb()`, and
|
---|
44 | `color-mod()` colors, as well as 3, 4, 6, and 8 digit hex colors, and named
|
---|
45 | colors without the need for additional plugins.
|
---|
46 |
|
---|
47 | Implemention details are available in
|
---|
48 | [the specification](https://drafts.csswg.org/css-color/#funcdef-color-mod).
|
---|
49 |
|
---|
50 | ### Supported Color Adjusters
|
---|
51 |
|
---|
52 | The `color-mod()` function accepts `red()`, `green()`, `blue()`, `a()` /
|
---|
53 | `alpha()`, `rgb()`, `h()` / `hue()`, `s()` / `saturation()`, `l()` /
|
---|
54 | `lightness()`, `w()` / `whiteness()`, `b()` / `blackness()`, `tint()`,
|
---|
55 | `shade()`, `blend()`, `blenda()`, and `contrast()` color adjusters.
|
---|
56 |
|
---|
57 | Implemention details are available in
|
---|
58 | [the specification](https://drafts.csswg.org/css-color/#typedef-color-adjuster).
|
---|
59 |
|
---|
60 | ### Supported Variables
|
---|
61 |
|
---|
62 | By default, `var()` variables will be used if their corresponding Custom
|
---|
63 | Properties are found in a `:root` rule, or if a fallback value is specified.
|
---|
64 |
|
---|
65 | ## Usage
|
---|
66 |
|
---|
67 | Add [PostCSS color-mod() Function] to your project:
|
---|
68 |
|
---|
69 | ```bash
|
---|
70 | npm install postcss-color-mod-function --save-dev
|
---|
71 | ```
|
---|
72 |
|
---|
73 | Use [PostCSS color-mod() Function] to process your CSS:
|
---|
74 |
|
---|
75 | ```js
|
---|
76 | const postcssColorMod = require('postcss-color-mod-function');
|
---|
77 |
|
---|
78 | postcssColorMod.process(YOUR_CSS /*, processOptions, pluginOptions */);
|
---|
79 | ```
|
---|
80 |
|
---|
81 | Or use it as a [PostCSS] plugin:
|
---|
82 |
|
---|
83 | ```js
|
---|
84 | const postcss = require('postcss');
|
---|
85 | const postcssColorMod = require('postcss-color-mod-function');
|
---|
86 |
|
---|
87 | postcss([
|
---|
88 | postcssColorMod(/* pluginOptions */)
|
---|
89 | ]).process(YOUR_CSS /*, processOptions */);
|
---|
90 | ```
|
---|
91 |
|
---|
92 | [PostCSS color-mod() Function] runs in all Node environments, with special instructions for:
|
---|
93 |
|
---|
94 | | [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Create React App](INSTALL.md#create-react-app) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
|
---|
95 | | --- | --- | --- | --- | --- | --- |
|
---|
96 |
|
---|
97 | ## Options
|
---|
98 |
|
---|
99 | ### stringifier
|
---|
100 |
|
---|
101 | The `stringifier` option defines how transformed colors will be produced in CSS.
|
---|
102 | By default, legacy `rbg()` and `rgba()` colors are produced, but this can be
|
---|
103 | easily updated to support [CSS Color Module Level 4 colors] colors.
|
---|
104 |
|
---|
105 | ```js
|
---|
106 | import postcssColorMod from 'postcss-color-mod-function';
|
---|
107 |
|
---|
108 | postcssColorMod({
|
---|
109 | stringifier(color) {
|
---|
110 | return color.toString(); // use CSS Color Module Level 4 colors (rgb, hsl, hwb)
|
---|
111 | }
|
---|
112 | });
|
---|
113 | ```
|
---|
114 |
|
---|
115 | Future major releases of [PostCSS color-mod() Function] may reverse this
|
---|
116 | functionality so that CSS Color Module Level 4 colors are produced by default.
|
---|
117 |
|
---|
118 | ### unresolved
|
---|
119 |
|
---|
120 | The `unresolved` option defines how unresolved functions and arguments should
|
---|
121 | be handled. The available options are `throw`, `warn`, and `ignore`. The
|
---|
122 | default option is to `throw`.
|
---|
123 |
|
---|
124 | If `ignore` is used, the `color-mod()` function will remain unchanged.
|
---|
125 |
|
---|
126 | ```js
|
---|
127 | import postcssColorMod from 'postcss-color-mod-function';
|
---|
128 |
|
---|
129 | postcssColorMod({
|
---|
130 | unresolved: 'ignore' // ignore unresolved color-mod() functions
|
---|
131 | });
|
---|
132 | ```
|
---|
133 |
|
---|
134 | ### transformVars
|
---|
135 |
|
---|
136 | The `transformVars` option defines whether `var()` variables used within
|
---|
137 | `color-mod()` should be transformed into their corresponding Custom Properties
|
---|
138 | available in `:root`, or their fallback value if it is specified. By default,
|
---|
139 | `var()` variables will be transformed.
|
---|
140 |
|
---|
141 | However, because these transformations occur at build time, they cannot be
|
---|
142 | considered accurate. Accurately resolving cascading variables relies on
|
---|
143 | knowledge of the living DOM tree.
|
---|
144 |
|
---|
145 | ### importFrom
|
---|
146 |
|
---|
147 | The `importFrom` option allows you to import variables from other sources,
|
---|
148 | which might be CSS, JS, and JSON files, and directly passed objects.
|
---|
149 |
|
---|
150 | ```js
|
---|
151 | postcssColorMod({
|
---|
152 | importFrom: 'path/to/file.css' // :root { --brand-dark: blue; --brand-main: var(--brand-dark); }
|
---|
153 | });
|
---|
154 | ```
|
---|
155 |
|
---|
156 | ```pcss
|
---|
157 | .brand-faded {
|
---|
158 | color: color-mod(var(--brand-main) a(50%));
|
---|
159 | }
|
---|
160 |
|
---|
161 | /* becomes */
|
---|
162 |
|
---|
163 | .brand-faded {
|
---|
164 | color: rgba(0, 0, 255, .5);
|
---|
165 | }
|
---|
166 | ```
|
---|
167 |
|
---|
168 | Multiple files can be passed into this option, and they will be parsed in the
|
---|
169 | order they were received. JavaScript files, JSON files, and objects will need
|
---|
170 | to namespace custom properties under a `customProperties` or
|
---|
171 | `custom-properties` key.
|
---|
172 |
|
---|
173 | ```js
|
---|
174 | postcssColorMod({
|
---|
175 | importFrom: [
|
---|
176 | 'path/to/file.css', // :root { --brand-dark: blue; --brand-main: var(--brand-dark); }
|
---|
177 | 'and/then/this.js', // module.exports = { customProperties: { '--brand-dark': 'blue', '--brand-main': 'var(--brand-dark)' } }
|
---|
178 | 'and/then/that.json', // { "custom-properties": { "--brand-dark": "blue", "--brand-main": "var(--brand-dark)" } }
|
---|
179 | {
|
---|
180 | customProperties: {
|
---|
181 | '--brand-dark': 'blue',
|
---|
182 | '--brand-main': 'var(--brand-dark)'
|
---|
183 | }
|
---|
184 | }
|
---|
185 | ]
|
---|
186 | });
|
---|
187 | ```
|
---|
188 |
|
---|
189 | Variables may reference other variables, and this plugin will attempt to
|
---|
190 | resolve them. If `transformVars` is set to `false` then `importFrom` will not
|
---|
191 | be used.
|
---|
192 |
|
---|
193 | [cli-img]: https://img.shields.io/travis/jonathantneal/postcss-color-mod-function.svg
|
---|
194 | [cli-url]: https://travis-ci.org/jonathantneal/postcss-color-mod-function
|
---|
195 | [css-img]: https://cssdb.org/badge/color-mod-function.svg
|
---|
196 | [css-url]: https://preset-env.cssdb.org/features#color-mod-function
|
---|
197 | [git-img]: https://img.shields.io/badge/support-chat-blue.svg
|
---|
198 | [git-url]: https://gitter.im/postcss/postcss
|
---|
199 | [npm-img]: https://img.shields.io/npm/v/postcss-color-mod-function.svg
|
---|
200 | [npm-url]: https://www.npmjs.com/package/postcss-color-mod-function
|
---|
201 |
|
---|
202 | [CSS Color Module Level 4]: https://www.w3.org/TR/css-color-4/#funcdef-color-mod
|
---|
203 | [Gulp PostCSS]: https://github.com/postcss/gulp-postcss
|
---|
204 | [Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
|
---|
205 | [PostCSS]: https://github.com/postcss/postcss
|
---|
206 | [PostCSS color-mod() Function]: https://github.com/jonathantneal/postcss-color-mod-function
|
---|