[6a3a178] | 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
|
---|