[6a3a178] | 1 | <div align="center">
|
---|
| 2 | <a href="https://colord.omgovich.ru/">
|
---|
| 3 | <img src="assets/logo.png" width="280" height="210" alt="colord" />
|
---|
| 4 | </a>
|
---|
| 5 | </div>
|
---|
| 6 |
|
---|
| 7 | <div align="center">
|
---|
| 8 | <a href="https://npmjs.org/package/colord">
|
---|
| 9 | <img alt="npm" src="https://img.shields.io/npm/v/colord.svg?labelColor=dd3a5e&color=6ead0a" />
|
---|
| 10 | </a>
|
---|
| 11 | <a href="https://github.com/omgovich/colord/actions">
|
---|
| 12 | <img alt="build" src="https://img.shields.io/github/workflow/status/omgovich/colord/Node.js%20CI/master.svg?labelColor=dd3a5e&color=6ead0a" />
|
---|
| 13 | </a>
|
---|
| 14 | <a href="https://codecov.io/gh/omgovich/colord">
|
---|
| 15 | <img alt="coverage" src="https://img.shields.io/codecov/c/github/omgovich/colord.svg?labelColor=dd3a5e&color=6ead0a" />
|
---|
| 16 | </a>
|
---|
| 17 | <a href="https://npmjs.org/package/colord">
|
---|
| 18 | <img alt="no dependencies" src="https://badgen.net/bundlephobia/dependency-count/colord?labelColor=dd3a5e&color=6ead0a" />
|
---|
| 19 | </a>
|
---|
| 20 | <a href="https://npmjs.org/package/colord">
|
---|
| 21 | <img alt="types included" src="https://badgen.net/npm/types/colord?labelColor=dd3a5e&color=6ead0a" />
|
---|
| 22 | </a>
|
---|
| 23 | </div>
|
---|
| 24 |
|
---|
| 25 | <div align="center">
|
---|
| 26 | <strong>Colord</strong> is a tiny yet powerful tool for high-performance color manipulations and conversions.
|
---|
| 27 | </div>
|
---|
| 28 |
|
---|
| 29 | ## Features
|
---|
| 30 |
|
---|
| 31 | - 📦 **Small**: Just **1.7 KB** gzipped ([3x+ lighter](#benchmarks) than **color** and **tinycolor2**)
|
---|
| 32 | - 🚀 **Fast**: [3x+ faster](#benchmarks) than **color** and **tinycolor2**
|
---|
| 33 | - 😍 **Simple**: Chainable API and familiar patterns
|
---|
| 34 | - 💪 **Immutable**: No need to worry about data mutations
|
---|
| 35 | - 🛡 **Bulletproof**: Written in strict TypeScript and has 100% test coverage
|
---|
| 36 | - 🗂 **Typed**: Ships with [types included](#types)
|
---|
| 37 | - 🏗 **Extendable**: Built-in [plugin system](#plugins) to add new functionality
|
---|
| 38 | - 📚 **CSS-compliant**: Strictly follows CSS Color Level specifications
|
---|
| 39 | - 👫 **Works everywhere**: Supports all browsers and Node.js
|
---|
| 40 | - 💨 **Dependency-free**
|
---|
| 41 |
|
---|
| 42 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 43 |
|
---|
| 44 | ## Benchmarks
|
---|
| 45 |
|
---|
| 46 | | Library | <nobr>Operations/sec</nobr> | Size<br /> (minified) | Size<br /> (gzipped) | Dependencies | Type declarations |
|
---|
| 47 | | ----------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
|
---|
| 48 | | <nobr><b>colord 👑</b></nobr> | <nobr><b>3,524,989</b></nobr> | [![](https://badgen.net/bundlephobia/min/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord) | [![](https://badgen.net/bundlephobia/minzip/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord) | [![](https://badgen.net/bundlephobia/dependency-count/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord) | [![](https://badgen.net/npm/types/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord) |
|
---|
| 49 | | color | 744,263 | [![](https://badgen.net/bundlephobia/min/color?color=red&label=)](https://bundlephobia.com/result?p=color) | [![](https://badgen.net/bundlephobia/minzip/color?color=red&label=)](https://bundlephobia.com/result?p=color) | [![](https://badgen.net/bundlephobia/dependency-count/color?color=red&label=)](https://bundlephobia.com/result?p=color) | [![](https://badgen.net/npm/types/color?color=e6591d&label=)](https://bundlephobia.com/result?p=color) |
|
---|
| 50 | | tinycolor2 | 971,312 | [![](https://badgen.net/bundlephobia/min/tinycolor2?color=red&label=)](https://bundlephobia.com/result?p=tinycolor2) | [![](https://badgen.net/bundlephobia/minzip/tinycolor2?color=red&label=)](https://bundlephobia.com/result?p=tinycolor2) | [![](https://badgen.net/bundlephobia/dependency-count/tinycolor2?color=6ead0a&label=)](https://bundlephobia.com/result?p=tinycolor2) | [![](https://badgen.net/npm/types/tinycolor2?color=e6591d&label=)](https://bundlephobia.com/result?p=tinycolor2) |
|
---|
| 51 | | ac-colors | 660,722 | [![](https://badgen.net/bundlephobia/min/ac-colors?color=e6591d&label=)](https://bundlephobia.com/result?p=ac-colors) | [![](https://badgen.net/bundlephobia/minzip/ac-colors?color=e6591d&label=)](https://bundlephobia.com/result?p=ac-colors) | [![](https://badgen.net/bundlephobia/dependency-count/ac-colors?color=6ead0a&label=)](https://bundlephobia.com/result?p=ac-colors) | [![](https://badgen.net/npm/types/ac-colors?color=red&label=)](https://bundlephobia.com/result?p=ac-colors) |
|
---|
| 52 | | chroma-js | 962,967 | [![](https://badgen.net/bundlephobia/min/chroma-js?color=red&label=)](https://bundlephobia.com/result?p=chroma-js) | [![](https://badgen.net/bundlephobia/minzip/chroma-js?color=red&label=)](https://bundlephobia.com/result?p=chroma-js) | [![](https://badgen.net/bundlephobia/dependency-count/chroma-js?color=red&label=)](https://bundlephobia.com/result?p=chroma-js) | [![](https://badgen.net/npm/types/chroma-js?color=e6591d&label=)](https://bundlephobia.com/result?p=chroma-js) |
|
---|
| 53 |
|
---|
| 54 | The performance results were generated on a MBP 2019, 2,6 GHz Intel Core i7 by running `npm run benchmark` in the library folder. See [tests/benchmark.ts](https://github.com/omgovich/colord/blob/master/tests/benchmark.ts).
|
---|
| 55 |
|
---|
| 56 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 57 |
|
---|
| 58 | ## Getting Started
|
---|
| 59 |
|
---|
| 60 | ```
|
---|
| 61 | npm i colord
|
---|
| 62 | ```
|
---|
| 63 |
|
---|
| 64 | ```js
|
---|
| 65 | import { colord } from "colord";
|
---|
| 66 |
|
---|
| 67 | colord("#ff0000").grayscale().alpha(0.25).toRgbString(); // "rgba(128, 128, 128, 0.25)"
|
---|
| 68 | colord("rgb(192, 192, 192)").isLight(); // true
|
---|
| 69 | colord("hsl(0, 50%, 50%)").darken(0.25).toHex(); // "#602020"
|
---|
| 70 | ```
|
---|
| 71 |
|
---|
| 72 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 73 |
|
---|
| 74 | ## Supported Color Models
|
---|
| 75 |
|
---|
| 76 | - Hexadecimal strings (including 3, 4 and 8 digit notations)
|
---|
| 77 | - RGB strings and objects
|
---|
| 78 | - HSL strings and objects
|
---|
| 79 | - HSV objects
|
---|
| 80 | - Color names ([via plugin](#plugins))
|
---|
| 81 | - HWB objects and strings ([via plugin](#plugins))
|
---|
| 82 | - CMYK objects and strings ([via plugin](#plugins))
|
---|
| 83 | - LCH objects and strings ([via plugin](#plugins))
|
---|
| 84 | - LAB objects ([via plugin](#plugins))
|
---|
| 85 | - XYZ objects ([via plugin](#plugins))
|
---|
| 86 |
|
---|
| 87 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 88 |
|
---|
| 89 | ## API
|
---|
| 90 |
|
---|
| 91 | ### Color parsing
|
---|
| 92 |
|
---|
| 93 | <details>
|
---|
| 94 | <summary><b><code>colord(input)</code></b></summary>
|
---|
| 95 |
|
---|
| 96 | Parses the given input and creates a new Colord instance. String parsing strictly conforms to [CSS Color Level Specifications](https://www.w3.org/TR/css-color-4/#color-type).
|
---|
| 97 |
|
---|
| 98 | ```js
|
---|
| 99 | import { colord } from "colord";
|
---|
| 100 |
|
---|
| 101 | // String input examples
|
---|
| 102 | colord("#FFF");
|
---|
| 103 | colord("#ffffff");
|
---|
| 104 | colord("#ffffffff");
|
---|
| 105 | colord("rgb(255, 255, 255)");
|
---|
| 106 | colord("rgba(255, 255, 255, 0.5)");
|
---|
| 107 | colord("rgba(100% 100% 100% / 50%)");
|
---|
| 108 | colord("hsl(90, 100%, 100%)");
|
---|
| 109 | colord("hsla(90, 100%, 100%, 0.5)");
|
---|
| 110 | colord("hsla(90deg 100% 100% / 50%)");
|
---|
| 111 | colord("tomato"); // requires "names" plugin
|
---|
| 112 |
|
---|
| 113 | // Object input examples
|
---|
| 114 | colord({ r: 255, g: 255, b: 255 });
|
---|
| 115 | colord({ r: 255, g: 255, b: 255, a: 1 });
|
---|
| 116 | colord({ h: 360, s: 100, l: 100 });
|
---|
| 117 | colord({ h: 360, s: 100, l: 100, a: 1 });
|
---|
| 118 | colord({ h: 360, s: 100, v: 100 });
|
---|
| 119 | colord({ h: 360, s: 100, v: 100, a: 1 });
|
---|
| 120 | ```
|
---|
| 121 |
|
---|
| 122 | Check out the ["Plugins"](#plugins) section for more input format examples.
|
---|
| 123 |
|
---|
| 124 | </details>
|
---|
| 125 |
|
---|
| 126 | <details>
|
---|
| 127 | <summary><b><code>getFormat(input)</code></b></summary>
|
---|
| 128 |
|
---|
| 129 | Returns a color model name for the input passed to the function. Uses the same parsing system as `colord` function.
|
---|
| 130 |
|
---|
| 131 | ```js
|
---|
| 132 | import { getFormat } from "colord";
|
---|
| 133 |
|
---|
| 134 | getFormat("#aabbcc"); // "hex"
|
---|
| 135 | getFormat({ r: 13, g: 237, b: 162, a: 0.5 }); // "rgb"
|
---|
| 136 | getFormat("hsl(180deg, 50%, 50%)"); // "hsl"
|
---|
| 137 | getFormat("WUT?"); // undefined
|
---|
| 138 | ```
|
---|
| 139 |
|
---|
| 140 | </details>
|
---|
| 141 |
|
---|
| 142 | ### Color conversion
|
---|
| 143 |
|
---|
| 144 | <details>
|
---|
| 145 | <summary><b><code>.toHex()</code></b></summary>
|
---|
| 146 |
|
---|
| 147 | Returns the [hexadecimal representation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors) of a color. When the alpha channel value of the color is less than 1, it outputs `#rrggbbaa` format instead of `#rrggbb`.
|
---|
| 148 |
|
---|
| 149 | ```js
|
---|
| 150 | colord("rgb(0, 255, 0)").toHex(); // "#00ff00"
|
---|
| 151 | colord({ h: 300, s: 100, l: 50 }).toHex(); // "#ff00ff"
|
---|
| 152 | colord({ r: 255, g: 255, b: 255, a: 0 }).toHex(); // "#ffffff00"
|
---|
| 153 | ```
|
---|
| 154 |
|
---|
| 155 | </details>
|
---|
| 156 |
|
---|
| 157 | <details>
|
---|
| 158 | <summary><b><code>.toRgb()</code></b></summary>
|
---|
| 159 |
|
---|
| 160 | ```js
|
---|
| 161 | colord("#ff0000").toRgb(); // { r: 255, g: 0, b: 0, a: 1 }
|
---|
| 162 | colord({ h: 180, s: 100, l: 50, a: 0.5 }).toRgb(); // { r: 0, g: 255, b: 255, a: 0.5 }
|
---|
| 163 | ```
|
---|
| 164 |
|
---|
| 165 | </details>
|
---|
| 166 |
|
---|
| 167 | <details>
|
---|
| 168 | <summary><b><code>.toRgbString()</code></b></summary>
|
---|
| 169 |
|
---|
| 170 | ```js
|
---|
| 171 | colord("#ff0000").toRgbString(); // "rgb(255, 0, 0)"
|
---|
| 172 | colord({ h: 180, s: 100, l: 50, a: 0.5 }).toRgbString(); // "rgba(0, 255, 255, 0.5)"
|
---|
| 173 | ```
|
---|
| 174 |
|
---|
| 175 | </details>
|
---|
| 176 |
|
---|
| 177 | <details>
|
---|
| 178 | <summary><b><code>.toHsl()</code></b></summary>
|
---|
| 179 |
|
---|
| 180 | Converts a color to [HSL color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and returns an object.
|
---|
| 181 |
|
---|
| 182 | ```js
|
---|
| 183 | colord("#ffff00").toHsl(); // { h: 60, s: 100, l: 50, a: 1 }
|
---|
| 184 | colord("rgba(0, 0, 255, 0.5) ").toHsl(); // { h: 240, s: 100, l: 50, a: 0.5 }
|
---|
| 185 | ```
|
---|
| 186 |
|
---|
| 187 | </details>
|
---|
| 188 |
|
---|
| 189 | <details>
|
---|
| 190 | <summary><b><code>.toHslString()</code></b></summary>
|
---|
| 191 |
|
---|
| 192 | Converts a color to [HSL color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and expresses it through the [functional notation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#hsl_colors).
|
---|
| 193 |
|
---|
| 194 | ```js
|
---|
| 195 | colord("#ffff00").toHslString(); // "hsl(60, 100%, 50%)"
|
---|
| 196 | colord("rgba(0, 0, 255, 0.5)").toHslString(); // "hsla(240, 100%, 50%, 0.5)"
|
---|
| 197 | ```
|
---|
| 198 |
|
---|
| 199 | </details>
|
---|
| 200 |
|
---|
| 201 | <details>
|
---|
| 202 | <summary><b><code>.toHsv()</code></b></summary>
|
---|
| 203 |
|
---|
| 204 | Converts a color to [HSV color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and returns an object.
|
---|
| 205 |
|
---|
| 206 | ```js
|
---|
| 207 | colord("#ffff00").toHsv(); // { h: 60, s: 100, v: 100, a: 1 }
|
---|
| 208 | colord("rgba(0, 255, 255, 0.5) ").toHsv(); // { h: 180, s: 100, v: 100, a: 1 }
|
---|
| 209 | ```
|
---|
| 210 |
|
---|
| 211 | </details>
|
---|
| 212 |
|
---|
| 213 | <details>
|
---|
| 214 | <summary><b><code>.toName(options?)</code></b> (<b>names</b> plugin)</summary>
|
---|
| 215 |
|
---|
| 216 | Converts a color to a [CSS keyword](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords). Returns `undefined` if the color is not specified in the specs.
|
---|
| 217 |
|
---|
| 218 | ```js
|
---|
| 219 | import { colord, extend } from "colord";
|
---|
| 220 | import namesPlugin from "colord/plugins/names";
|
---|
| 221 |
|
---|
| 222 | extend([namesPlugin]);
|
---|
| 223 |
|
---|
| 224 | colord("#ff6347").toName(); // "tomato"
|
---|
| 225 | colord("#00ffff").toName(); // "cyan"
|
---|
| 226 | colord("rgba(0, 0, 0, 0)").toName(); // "transparent"
|
---|
| 227 |
|
---|
| 228 | colord("#fe0000").toName(); // undefined (the color is not specified in CSS specs)
|
---|
| 229 | colord("#fe0000").toName({ closest: true }); // "red" (closest color available)
|
---|
| 230 | ```
|
---|
| 231 |
|
---|
| 232 | </details>
|
---|
| 233 |
|
---|
| 234 | <details>
|
---|
| 235 | <summary><b><code>.toCmyk()</code></b> (<b>cmyk</b> plugin)</summary>
|
---|
| 236 |
|
---|
| 237 | Converts a color to [CMYK](https://en.wikipedia.org/wiki/CMYK_color_model) color space.
|
---|
| 238 |
|
---|
| 239 | ```js
|
---|
| 240 | import { colord, extend } from "colord";
|
---|
| 241 | import cmykPlugin from "colord/plugins/cmyk";
|
---|
| 242 |
|
---|
| 243 | extend([cmykPlugin]);
|
---|
| 244 |
|
---|
| 245 | colord("#ffffff").toCmyk(); // { c: 0, m: 0, y: 0, k: 0, a: 1 }
|
---|
| 246 | colord("#555aaa").toCmyk(); // { c: 50, m: 47, y: 0, k: 33, a: 1 }
|
---|
| 247 | ```
|
---|
| 248 |
|
---|
| 249 | </details>
|
---|
| 250 |
|
---|
| 251 | <details>
|
---|
| 252 | <summary><b><code>.toCmykString()</code></b> (<b>cmyk</b> plugin)</summary>
|
---|
| 253 |
|
---|
| 254 | Converts a color to color space.
|
---|
| 255 |
|
---|
| 256 | Converts a color to [CMYK](https://en.wikipedia.org/wiki/CMYK_color_model) color space and expresses it through the [functional notation](https://www.w3.org/TR/css-color-4/#device-cmyk)
|
---|
| 257 |
|
---|
| 258 | ```js
|
---|
| 259 | import { colord, extend } from "colord";
|
---|
| 260 | import cmykPlugin from "colord/plugins/cmyk";
|
---|
| 261 |
|
---|
| 262 | extend([cmykPlugin]);
|
---|
| 263 |
|
---|
| 264 | colord("#99ffff").toCmykString(); // "device-cmyk(40% 0% 0% 0%)"
|
---|
| 265 | colord("#00336680").toCmykString(); // "device-cmyk(100% 50% 0% 60% / 0.5)"
|
---|
| 266 | ```
|
---|
| 267 |
|
---|
| 268 | </details>
|
---|
| 269 |
|
---|
| 270 | <details>
|
---|
| 271 | <summary><b><code>.toHwb()</code></b> (<b>hwb</b> plugin)</summary>
|
---|
| 272 |
|
---|
| 273 | Converts a color to [HWB (Hue-Whiteness-Blackness)](https://en.wikipedia.org/wiki/HWB_color_model) color space.
|
---|
| 274 |
|
---|
| 275 | ```js
|
---|
| 276 | import { colord, extend } from "colord";
|
---|
| 277 | import hwbPlugin from "colord/plugins/hwb";
|
---|
| 278 |
|
---|
| 279 | extend([hwbPlugin]);
|
---|
| 280 |
|
---|
| 281 | colord("#ffffff").toHwb(); // { h: 0, w: 100, b: 0, a: 1 }
|
---|
| 282 | colord("#555aaa").toHwb(); // { h: 236, w: 33, b: 33, a: 1 }
|
---|
| 283 | ```
|
---|
| 284 |
|
---|
| 285 | </details>
|
---|
| 286 |
|
---|
| 287 | <details>
|
---|
| 288 | <summary><b><code>.toHwbString()</code></b> (<b>hwb</b> plugin)</summary>
|
---|
| 289 |
|
---|
| 290 | Converts a color to [HWB (Hue-Whiteness-Blackness)](https://en.wikipedia.org/wiki/HWB_color_model) color space and expresses it through the [functional notation](https://www.w3.org/TR/css-color-4/#the-hwb-notation).
|
---|
| 291 |
|
---|
| 292 | ```js
|
---|
| 293 | import { colord, extend } from "colord";
|
---|
| 294 | import hwbPlugin from "colord/plugins/hwb";
|
---|
| 295 |
|
---|
| 296 | extend([hwbPlugin]);
|
---|
| 297 |
|
---|
| 298 | colord("#999966").toHwbString(); // "hwb(60 40% 40%)"
|
---|
| 299 | colord("#99ffff").toHwbString(); // "hwb(180 60% 0%)"
|
---|
| 300 | colord("#003366").alpha(0.5).toHwbString(); // "hwb(210 0% 60% / 0.5)"
|
---|
| 301 | ```
|
---|
| 302 |
|
---|
| 303 | </details>
|
---|
| 304 |
|
---|
| 305 | <details>
|
---|
| 306 | <summary><b><code>.toLab()</code></b> (<b>lab</b> plugin)</summary>
|
---|
| 307 |
|
---|
| 308 | Converts a color to [CIE LAB](https://en.wikipedia.org/wiki/CIELAB_color_space) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).
|
---|
| 309 |
|
---|
| 310 | ```js
|
---|
| 311 | import { colord, extend } from "colord";
|
---|
| 312 | import labPlugin from "colord/plugins/lab";
|
---|
| 313 |
|
---|
| 314 | extend([labPlugin]);
|
---|
| 315 |
|
---|
| 316 | colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }
|
---|
| 317 | colord("#33221180").toLab(); // { l: 14.89, a: 5.77, b: 14.41, alpha: 0.5 }
|
---|
| 318 | ```
|
---|
| 319 |
|
---|
| 320 | </details>
|
---|
| 321 |
|
---|
| 322 | <details>
|
---|
| 323 | <summary><b><code>.toLch()</code></b> (<b>lch</b> plugin)</summary>
|
---|
| 324 |
|
---|
| 325 | Converts a color to [CIE LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).
|
---|
| 326 |
|
---|
| 327 | ```js
|
---|
| 328 | import { colord, extend } from "colord";
|
---|
| 329 | import lchPlugin from "colord/plugins/lch";
|
---|
| 330 |
|
---|
| 331 | extend([lchPlugin]);
|
---|
| 332 |
|
---|
| 333 | colord("#ffffff").toLch(); // { l: 100, c: 0, h: 0, a: 1 }
|
---|
| 334 | colord("#213b0b").toLch(); // { l: 21.85, c: 31.95, h: 127.77, a: 1 }
|
---|
| 335 | ```
|
---|
| 336 |
|
---|
| 337 | </details>
|
---|
| 338 |
|
---|
| 339 | <details>
|
---|
| 340 | <summary><b><code>.toLchString()</code></b> (<b>lch</b> plugin)</summary>
|
---|
| 341 |
|
---|
| 342 | Converts a color to [CIE LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space and expresses it through the [functional notation](https://www.w3.org/TR/css-color-4/#specifying-lab-lch).
|
---|
| 343 |
|
---|
| 344 | ```js
|
---|
| 345 | import { colord, extend } from "colord";
|
---|
| 346 | import lchPlugin from "colord/plugins/lch";
|
---|
| 347 |
|
---|
| 348 | extend([lchPlugin]);
|
---|
| 349 |
|
---|
| 350 | colord("#ffffff").toLchString(); // "lch(100% 0 0)"
|
---|
| 351 | colord("#213b0b").alpha(0.5).toLchString(); // "lch(21.85% 31.95 127.77 / 0.5)"
|
---|
| 352 | ```
|
---|
| 353 |
|
---|
| 354 | </details>
|
---|
| 355 |
|
---|
| 356 | <details>
|
---|
| 357 | <summary><b><code>.toXyz()</code></b> (<b>xyz</b> plugin)</summary>
|
---|
| 358 |
|
---|
| 359 | Converts a color to [CIE XYZ](https://www.sttmedia.com/colormodel-xyz) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).
|
---|
| 360 |
|
---|
| 361 | ```js
|
---|
| 362 | import { colord, extend } from "colord";
|
---|
| 363 | import xyzPlugin from "colord/plugins/xyz";
|
---|
| 364 |
|
---|
| 365 | extend([xyzPlugin]);
|
---|
| 366 |
|
---|
| 367 | colord("#ffffff").toXyz(); // { x: 95.047, y: 100, z: 108.883, a: 1 }
|
---|
| 368 | ```
|
---|
| 369 |
|
---|
| 370 | </details>
|
---|
| 371 |
|
---|
| 372 | ### Color manipulation
|
---|
| 373 |
|
---|
| 374 | <details>
|
---|
| 375 | <summary><b><code>.alpha(value)</code></b></summary>
|
---|
| 376 |
|
---|
| 377 | Changes the alpha channel value and returns a new `Colord` instance.
|
---|
| 378 |
|
---|
| 379 | ```js
|
---|
| 380 | colord("rgb(0, 0, 0)").alpha(0.5).toRgbString(); // "rgba(0, 0, 0, 0.5)"
|
---|
| 381 | ```
|
---|
| 382 |
|
---|
| 383 | </details>
|
---|
| 384 |
|
---|
| 385 | <details>
|
---|
| 386 | <summary><b><code>.invert()</code></b></summary>
|
---|
| 387 |
|
---|
| 388 | Creates a new `Colord` instance containing an inverted (opposite) version of the color.
|
---|
| 389 |
|
---|
| 390 | ```js
|
---|
| 391 | colord("#ffffff").invert().toHex(); // "#000000"
|
---|
| 392 | colord("#aabbcc").invert().toHex(); // "#554433"
|
---|
| 393 | ```
|
---|
| 394 |
|
---|
| 395 | </details>
|
---|
| 396 |
|
---|
| 397 | <details>
|
---|
| 398 | <summary><b><code>.saturate(amount = 0.1)</code></b></summary>
|
---|
| 399 |
|
---|
| 400 | Increases the [HSL saturation](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
|
---|
| 401 |
|
---|
| 402 | ```js
|
---|
| 403 | colord("#bf4040").saturate(0.25).toHex(); // "#df2020"
|
---|
| 404 | colord("hsl(0, 50%, 50%)").saturate(0.5).toHslString(); // "hsl(0, 100%, 50%)"
|
---|
| 405 | ```
|
---|
| 406 |
|
---|
| 407 | </details>
|
---|
| 408 |
|
---|
| 409 | <details>
|
---|
| 410 | <summary><b><code>.desaturate(amount = 0.1)</code></b></summary>
|
---|
| 411 |
|
---|
| 412 | Decreases the [HSL saturation](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
|
---|
| 413 |
|
---|
| 414 | ```js
|
---|
| 415 | colord("#df2020").saturate(0.25).toHex(); // "#bf4040"
|
---|
| 416 | colord("hsl(0, 100%, 50%)").saturate(0.5).toHslString(); // "hsl(0, 50%, 50%)"
|
---|
| 417 | ```
|
---|
| 418 |
|
---|
| 419 | </details>
|
---|
| 420 |
|
---|
| 421 | <details>
|
---|
| 422 | <summary><b><code>.grayscale()</code></b></summary>
|
---|
| 423 |
|
---|
| 424 | Makes a gray color with the same lightness as a source color. Same as calling `desaturate(1)`.
|
---|
| 425 |
|
---|
| 426 | ```js
|
---|
| 427 | colord("#bf4040").grayscale().toHex(); // "#808080"
|
---|
| 428 | colord("hsl(0, 100%, 50%)").grayscale().toHslString(); // "hsl(0, 0%, 50%)"
|
---|
| 429 | ```
|
---|
| 430 |
|
---|
| 431 | </details>
|
---|
| 432 |
|
---|
| 433 | <details>
|
---|
| 434 | <summary><b><code>.lighten(amount = 0.1)</code></b></summary>
|
---|
| 435 |
|
---|
| 436 | Increases the [HSL lightness](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
|
---|
| 437 |
|
---|
| 438 | ```js
|
---|
| 439 | colord("#000000").lighten(0.5).toHex(); // "#808080"
|
---|
| 440 | colord("#223344").lighten(0.3).toHex(); // "#5580aa"
|
---|
| 441 | colord("hsl(0, 50%, 50%)").lighten(0.5).toHslString(); // "hsl(0, 50%, 100%)"
|
---|
| 442 | ```
|
---|
| 443 |
|
---|
| 444 | </details>
|
---|
| 445 |
|
---|
| 446 | <details>
|
---|
| 447 | <summary><b><code>.darken(amount = 0.1)</code></b></summary>
|
---|
| 448 |
|
---|
| 449 | Decreases the [HSL lightness](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
|
---|
| 450 |
|
---|
| 451 | ```js
|
---|
| 452 | colord("#ffffff").darken(0.5).toHex(); // "#808080"
|
---|
| 453 | colord("#5580aa").darken(0.3).toHex(); // "#223344"
|
---|
| 454 | colord("hsl(0, 50%, 100%)").lighten(0.5).toHslString(); // "hsl(0, 50%, 50%)"
|
---|
| 455 | ```
|
---|
| 456 |
|
---|
| 457 | </details>
|
---|
| 458 |
|
---|
| 459 | <details>
|
---|
| 460 | <summary><b><code>.hue(value)</code></b></summary>
|
---|
| 461 |
|
---|
| 462 | Changes the hue value and returns a new `Colord` instance.
|
---|
| 463 |
|
---|
| 464 | ```js
|
---|
| 465 | colord("hsl(90, 50%, 50%)").hue(180).toHslString(); // "hsl(180, 50%, 50%)"
|
---|
| 466 | colord("hsl(90, 50%, 50%)").hue(370).toHslString(); // "hsl(10, 50%, 50%)"
|
---|
| 467 | ```
|
---|
| 468 |
|
---|
| 469 | </details>
|
---|
| 470 |
|
---|
| 471 | <details>
|
---|
| 472 | <summary><b><code>.rotate(amount = 15)</code></b></summary>
|
---|
| 473 |
|
---|
| 474 | Increases the [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV) hue value of a color by the given amount.
|
---|
| 475 |
|
---|
| 476 | ```js
|
---|
| 477 | colord("hsl(90, 50%, 50%)").rotate(90).toHslString(); // "hsl(180, 50%, 50%)"
|
---|
| 478 | colord("hsl(90, 50%, 50%)").rotate(-180).toHslString(); // "hsl(270, 50%, 50%)"
|
---|
| 479 | ```
|
---|
| 480 |
|
---|
| 481 | </details>
|
---|
| 482 |
|
---|
| 483 | <details>
|
---|
| 484 | <summary><b><code>.mix(color2, ratio = 0.5)</code></b> (<b>mix</b> plugin)</summary>
|
---|
| 485 |
|
---|
| 486 | Produces a mixture of two colors and returns the result of mixing them (new Colord instance).
|
---|
| 487 |
|
---|
| 488 | In contrast to other libraries that perform RGB values mixing, Colord mixes colors through [LAB color space](https://en.wikipedia.org/wiki/CIELAB_color_space). This approach produces better results and doesn't have the drawbacks the legacy way has.
|
---|
| 489 |
|
---|
| 490 | → [Online demo](https://3cg7o.csb.app/)
|
---|
| 491 |
|
---|
| 492 | ```js
|
---|
| 493 | import { colord, extend } from "colord";
|
---|
| 494 | import mixPlugin from "colord/plugins/mix";
|
---|
| 495 |
|
---|
| 496 | extend([mixPlugin]);
|
---|
| 497 |
|
---|
| 498 | colord("#ffffff").mix("#000000").toHex(); // "#777777"
|
---|
| 499 | colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
|
---|
| 500 | colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#e3c07e"
|
---|
| 501 | colord("#008080").mix("#808000", 0.35).toHex(); // "#50805d"
|
---|
| 502 | ```
|
---|
| 503 |
|
---|
| 504 | </details>
|
---|
| 505 |
|
---|
| 506 | <details>
|
---|
| 507 | <summary><b><code>.tints(count = 5)</code></b> (<b>mix</b> plugin)</summary>
|
---|
| 508 |
|
---|
| 509 | Provides functionality to generate [tints](https://en.wikipedia.org/wiki/Tints_and_shades) of a color. Returns an array of `Colord` instances, including the original color.
|
---|
| 510 |
|
---|
| 511 | ```js
|
---|
| 512 | import { colord, extend } from "colord";
|
---|
| 513 | import mixPlugin from "colord/plugins/mix";
|
---|
| 514 |
|
---|
| 515 | extend([mixPlugin]);
|
---|
| 516 |
|
---|
| 517 | const color = colord("#ff0000");
|
---|
| 518 | color.tints(3).map((c) => c.toHex()); // ["#ff0000", "#ff9f80", "#ffffff"];
|
---|
| 519 | ```
|
---|
| 520 |
|
---|
| 521 | </details>
|
---|
| 522 |
|
---|
| 523 | <details>
|
---|
| 524 | <summary><b><code>.shades(count = 5)</code></b> (<b>mix</b> plugin)</summary>
|
---|
| 525 |
|
---|
| 526 | Provides functionality to generate [shades](https://en.wikipedia.org/wiki/Tints_and_shades) of a color. Returns an array of `Colord` instances, including the original color.
|
---|
| 527 |
|
---|
| 528 | ```js
|
---|
| 529 | import { colord, extend } from "colord";
|
---|
| 530 | import mixPlugin from "colord/plugins/mix";
|
---|
| 531 |
|
---|
| 532 | extend([mixPlugin]);
|
---|
| 533 |
|
---|
| 534 | const color = colord("#ff0000");
|
---|
| 535 | color.shades(3).map((c) => c.toHex()); // ["#ff0000", "#7a1b0b", "#000000"];
|
---|
| 536 | ```
|
---|
| 537 |
|
---|
| 538 | </details>
|
---|
| 539 |
|
---|
| 540 | <details>
|
---|
| 541 | <summary><b><code>.tones(count = 5)</code></b> (<b>mix</b> plugin)</summary>
|
---|
| 542 |
|
---|
| 543 | Provides functionality to generate [tones](https://en.wikipedia.org/wiki/Tints_and_shades) of a color. Returns an array of `Colord` instances, including the original color.
|
---|
| 544 |
|
---|
| 545 | ```js
|
---|
| 546 | import { colord, extend } from "colord";
|
---|
| 547 | import mixPlugin from "colord/plugins/mix";
|
---|
| 548 |
|
---|
| 549 | extend([mixPlugin]);
|
---|
| 550 |
|
---|
| 551 | const color = colord("#ff0000");
|
---|
| 552 | color.tones(3).map((c) => c.toHex()); // ["#ff0000", "#c86147", "#808080"];
|
---|
| 553 | ```
|
---|
| 554 |
|
---|
| 555 | </details>
|
---|
| 556 |
|
---|
| 557 | <details>
|
---|
| 558 | <summary><b><code>.harmonies(type = "complementary")</code></b> (<b>harmonies</b> plugin)</summary>
|
---|
| 559 |
|
---|
| 560 | Provides functionality to generate [harmony colors](<https://en.wikipedia.org/wiki/Harmony_(color)>). Returns an array of `Colord` instances.
|
---|
| 561 |
|
---|
| 562 | ```js
|
---|
| 563 | import { colord, extend } from "colord";
|
---|
| 564 | import harmoniesPlugin from "colord/plugins/harmonies";
|
---|
| 565 |
|
---|
| 566 | extend([harmoniesPlugin]);
|
---|
| 567 |
|
---|
| 568 | const color = colord("#ff0000");
|
---|
| 569 | color.harmonies("analogous").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000"]
|
---|
| 570 | color.harmonies("complementary").map((c) => c.toHex()); // ["#ff0000", "#00ffff"]
|
---|
| 571 | color.harmonies("double-split-complementary").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000", "#00ff80", "#0080ff"]
|
---|
| 572 | color.harmonies("rectangle").map((c) => c.toHex()); // ["#ff0000", "#ffff00", "#00ffff", "#0000ff"]
|
---|
| 573 | color.harmonies("split-complementary").map((c) => c.toHex()); // ["#ff0000", "#00ff80", "#0080ff"]
|
---|
| 574 | color.harmonies("tetradic").map((c) => c.toHex()); // ["#ff0000", "#80ff00", "#00ffff", "#8000ff"]
|
---|
| 575 | color.harmonies("triadic").map((c) => c.toHex()); // ["#ff0000", "#00ff00", "#0000ff"]
|
---|
| 576 | ```
|
---|
| 577 |
|
---|
| 578 | </details>
|
---|
| 579 |
|
---|
| 580 | ### Color analysis
|
---|
| 581 |
|
---|
| 582 | <details>
|
---|
| 583 | <summary><b><code>.isValid()</code></b></summary>
|
---|
| 584 |
|
---|
| 585 | Returns a boolean indicating whether or not an input has been parsed successfully.
|
---|
| 586 | Note: If parsing is unsuccessful, Colord defaults to black (does not throws an error).
|
---|
| 587 |
|
---|
| 588 | ```js
|
---|
| 589 | colord("#ffffff").isValid(); // true
|
---|
| 590 | colord("#wwuutt").isValid(); // false
|
---|
| 591 | colord("abracadabra").isValid(); // false
|
---|
| 592 | colord({ r: 0, g: 0, b: 0 }).isValid(); // true
|
---|
| 593 | colord({ r: 0, g: 0, v: 0 }).isValid(); // false
|
---|
| 594 | ```
|
---|
| 595 |
|
---|
| 596 | </details>
|
---|
| 597 |
|
---|
| 598 | <details>
|
---|
| 599 | <summary><b><code>.isEqual(color2)</code></b></summary>
|
---|
| 600 |
|
---|
| 601 | Determines whether two values are the same color.
|
---|
| 602 |
|
---|
| 603 | ```js
|
---|
| 604 | colord("#000000").isEqual("rgb(0, 0, 0)"); // true
|
---|
| 605 | colord("#000000").isEqual("rgb(255, 255, 255)"); // false
|
---|
| 606 | ```
|
---|
| 607 |
|
---|
| 608 | </details>
|
---|
| 609 |
|
---|
| 610 | <details>
|
---|
| 611 | <summary><b><code>.alpha()</code></b></summary>
|
---|
| 612 |
|
---|
| 613 | ```js
|
---|
| 614 | colord("#ffffff").alpha(); // 1
|
---|
| 615 | colord("rgba(50, 100, 150, 0.5)").alpha(); // 0.5
|
---|
| 616 | ```
|
---|
| 617 |
|
---|
| 618 | </details>
|
---|
| 619 |
|
---|
| 620 | <details>
|
---|
| 621 | <summary><b><code>.hue()</code></b></summary>
|
---|
| 622 |
|
---|
| 623 | ```js
|
---|
| 624 | colord("hsl(90, 50%, 50%)").hue(); // 90
|
---|
| 625 | colord("hsl(-10, 50%, 50%)").hue(); // 350
|
---|
| 626 | ```
|
---|
| 627 |
|
---|
| 628 | </details>
|
---|
| 629 |
|
---|
| 630 | <details>
|
---|
| 631 | <summary><b><code>.brightness()</code></b></summary>
|
---|
| 632 |
|
---|
| 633 | Returns the brightness of a color (from 0 to 1). The calculation logic is modified from [Web Content Accessibility Guidelines](https://www.w3.org/TR/AERT/#color-contrast).
|
---|
| 634 |
|
---|
| 635 | ```js
|
---|
| 636 | colord("#000000").brightness(); // 0
|
---|
| 637 | colord("#808080").brightness(); // 0.5
|
---|
| 638 | colord("#ffffff").brightness(); // 1
|
---|
| 639 | ```
|
---|
| 640 |
|
---|
| 641 | </details>
|
---|
| 642 |
|
---|
| 643 | <details>
|
---|
| 644 | <summary><b><code>.isLight()</code></b></summary>
|
---|
| 645 |
|
---|
| 646 | Same as calling `brightness() >= 0.5`.
|
---|
| 647 |
|
---|
| 648 | ```js
|
---|
| 649 | colord("#111111").isLight(); // false
|
---|
| 650 | colord("#aabbcc").isLight(); // true
|
---|
| 651 | colord("#ffffff").isLight(); // true
|
---|
| 652 | ```
|
---|
| 653 |
|
---|
| 654 | </details>
|
---|
| 655 |
|
---|
| 656 | <details>
|
---|
| 657 | <summary><b><code>.isDark()</code></b></summary>
|
---|
| 658 |
|
---|
| 659 | Same as calling `brightness() < 0.5`.
|
---|
| 660 |
|
---|
| 661 | ```js
|
---|
| 662 | colord("#111111").isDark(); // true
|
---|
| 663 | colord("#aabbcc").isDark(); // false
|
---|
| 664 | colord("#ffffff").isDark(); // false
|
---|
| 665 | ```
|
---|
| 666 |
|
---|
| 667 | </details>
|
---|
| 668 |
|
---|
| 669 | <details>
|
---|
| 670 | <summary><b><code>.luminance()</code></b> (<b>a11y</b> plugin)</summary>
|
---|
| 671 |
|
---|
| 672 | Returns the relative luminance of a color, normalized to 0 for darkest black and 1 for lightest white as defined by [WCAG 2.0](https://www.w3.org/TR/WCAG20/#relativeluminancedef).
|
---|
| 673 |
|
---|
| 674 | ```js
|
---|
| 675 | colord("#000000").luminance(); // 0
|
---|
| 676 | colord("#808080").luminance(); // 0.22
|
---|
| 677 | colord("#ccddee").luminance(); // 0.71
|
---|
| 678 | colord("#ffffff").luminance(); // 1
|
---|
| 679 | ```
|
---|
| 680 |
|
---|
| 681 | </details>
|
---|
| 682 |
|
---|
| 683 | <details>
|
---|
| 684 | <summary><b><code>.contrast(color2 = "#FFF")</code></b> (<b>a11y</b> plugin)</summary>
|
---|
| 685 |
|
---|
| 686 | Calculates a contrast ratio for a color pair. This luminance difference is expressed as a ratio ranging from 1 (e.g. white on white) to 21 (e.g., black on a white). [WCAG Accessibility Level AA requires](https://webaim.org/articles/contrast/) a ratio of at least 4.5 for normal text and 3 for large text.
|
---|
| 687 |
|
---|
| 688 | ```js
|
---|
| 689 | colord("#000000").contrast(); // 21 (black on white)
|
---|
| 690 | colord("#ffffff").contrast("#000000"); // 21 (white on black)
|
---|
| 691 | colord("#777777").contrast(); // 4.47 (gray on white)
|
---|
| 692 | colord("#ff0000").contrast(); // 3.99 (red on white)
|
---|
| 693 | colord("#0000ff").contrast("#ff000"); // 2.14 (blue on red)
|
---|
| 694 | ```
|
---|
| 695 |
|
---|
| 696 | </details>
|
---|
| 697 |
|
---|
| 698 | <details>
|
---|
| 699 | <summary><b><code>.isReadable(color2 = "#FFF", options?)</code></b> (<b>a11y</b> plugin)</summary>
|
---|
| 700 |
|
---|
| 701 | Checks that a background and text color pair is readable according to [WCAG 2.0 Contrast and Color Requirements](https://webaim.org/articles/contrast/).
|
---|
| 702 |
|
---|
| 703 | ```js
|
---|
| 704 | colord("#000000").isReadable(); // true (normal black text on white bg conforms to WCAG AA)
|
---|
| 705 | colord("#777777").isReadable(); // false (normal gray text on white bg conforms to WCAG AA)
|
---|
| 706 | colord("#ffffff").isReadable("#000000"); // true (normal white text on black bg conforms to WCAG AA)
|
---|
| 707 | colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
|
---|
| 708 | colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
|
---|
| 709 | colord("#e60000").isReadable("#ffff47", { level: "AAA", size: "large" }); // true (large red text on yellow bg conforms to WCAG AAA)
|
---|
| 710 | ```
|
---|
| 711 |
|
---|
| 712 | </details>
|
---|
| 713 |
|
---|
| 714 | <details>
|
---|
| 715 | <summary><b><code>.delta(color2 = "#FFF")</code></b> (<b>lab</b> plugin)</summary>
|
---|
| 716 |
|
---|
| 717 | Calculates the perceived color difference between two colors.
|
---|
| 718 | The difference calculated according to [Delta E2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).
|
---|
| 719 | The return value is `0` if the colors are equal, `1` if they are entirely different.
|
---|
| 720 |
|
---|
| 721 | ```js
|
---|
| 722 | colord("#3296fa").delta("#197dc8"); // 0.099
|
---|
| 723 | colord("#faf0c8").delta("#ffffff"); // 0.148
|
---|
| 724 | colord("#afafaf").delta("#b4b4b4"); // 0.014
|
---|
| 725 | colord("#000000").delta("#ffffff"); // 1
|
---|
| 726 | ```
|
---|
| 727 |
|
---|
| 728 | </details>
|
---|
| 729 |
|
---|
| 730 | ### Color utilities
|
---|
| 731 |
|
---|
| 732 | <details>
|
---|
| 733 | <summary><b><code>random()</code></b></summary>
|
---|
| 734 |
|
---|
| 735 | Returns a new Colord instance with a random color value inside.
|
---|
| 736 |
|
---|
| 737 | ```js
|
---|
| 738 | import { random } from "colord";
|
---|
| 739 |
|
---|
| 740 | random().toHex(); // "#01c8ec"
|
---|
| 741 | random().alpha(0.5).toRgb(); // { r: 13, g: 237, b: 162, a: 0.5 }
|
---|
| 742 | ```
|
---|
| 743 |
|
---|
| 744 | </details>
|
---|
| 745 |
|
---|
| 746 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 747 |
|
---|
| 748 | ## Plugins
|
---|
| 749 |
|
---|
| 750 | **Colord** has a built-in plugin system that allows new features and functionality to be easily added.
|
---|
| 751 |
|
---|
| 752 | <details>
|
---|
| 753 | <summary><b><code>a11y</code> (Accessibility)</b> <i>0.38 KB</i></summary>
|
---|
| 754 |
|
---|
| 755 | Adds accessibility and color contrast utilities working according to [Web Content Accessibility Guidelines 2.0](https://www.w3.org/TR/WCAG20/).
|
---|
| 756 |
|
---|
| 757 | ```js
|
---|
| 758 | import { colord, extend } from "colord";
|
---|
| 759 | import a11yPlugin from "colord/plugins/a11y";
|
---|
| 760 |
|
---|
| 761 | extend([a11yPlugin]);
|
---|
| 762 |
|
---|
| 763 | colord("#000000").luminance(); // 0
|
---|
| 764 | colord("#ccddee").luminance(); // 0.71
|
---|
| 765 | colord("#ffffff").luminance(); // 1
|
---|
| 766 |
|
---|
| 767 | colord("#000000").contrast(); // 21 (black on white)
|
---|
| 768 | colord("#ffffff").contrast("#000000"); // 21 (white on black)
|
---|
| 769 | colord("#0000ff").contrast("#ff000"); // 2.14 (blue on red)
|
---|
| 770 |
|
---|
| 771 | colord("#000000").isReadable(); // true (black on white)
|
---|
| 772 | colord("#ffffff").isReadable("#000000"); // true (white on black)
|
---|
| 773 | colord("#777777").isReadable(); // false (gray on white)
|
---|
| 774 | colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
|
---|
| 775 | colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
|
---|
| 776 | colord("#e60000").isReadable("#ffff47", { level: "AAA", size: "large" }); // true (large red text on yellow bg conforms to WCAG AAA)
|
---|
| 777 | ```
|
---|
| 778 |
|
---|
| 779 | </details>
|
---|
| 780 |
|
---|
| 781 | <details>
|
---|
| 782 | <summary><b><code>cmyk</code> (CMYK color space)</b> <i>0.6 KB</i></summary>
|
---|
| 783 |
|
---|
| 784 | Adds support of [CMYK](https://www.sttmedia.com/colormodel-cmyk) color model.
|
---|
| 785 |
|
---|
| 786 | ```js
|
---|
| 787 | import { colord, extend } from "colord";
|
---|
| 788 | import cmykPlugin from "colord/plugins/cmyk";
|
---|
| 789 |
|
---|
| 790 | extend([cmykPlugin]);
|
---|
| 791 |
|
---|
| 792 | colord("#ffffff").toCmyk(); // { c: 0, m: 0, y: 0, k: 0, a: 1 }
|
---|
| 793 | colord("#999966").toCmykString(); // "device-cmyk(0% 0% 33% 40%)"
|
---|
| 794 | colord({ c: 0, m: 0, y: 0, k: 100, a: 1 }).toHex(); // "#000000"
|
---|
| 795 | colord("device-cmyk(0% 61% 72% 0% / 50%)").toHex(); // "#ff634780"
|
---|
| 796 | ```
|
---|
| 797 |
|
---|
| 798 | </details>
|
---|
| 799 |
|
---|
| 800 | <details>
|
---|
| 801 | <summary><b><code>harmonies</code> (Color harmonies)</b> <i>0.15 KB</i></summary>
|
---|
| 802 |
|
---|
| 803 | Provides functionality to generate [harmony colors](<https://en.wikipedia.org/wiki/Harmony_(color)>).
|
---|
| 804 |
|
---|
| 805 | ```js
|
---|
| 806 | import { colord, extend } from "colord";
|
---|
| 807 | import harmonies from "colord/plugins/harmonies";
|
---|
| 808 |
|
---|
| 809 | extend([harmonies]);
|
---|
| 810 |
|
---|
| 811 | const color = colord("#ff0000");
|
---|
| 812 | color.harmonies("analogous").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000"]
|
---|
| 813 | color.harmonies("complementary").map((c) => c.toHex()); // ["#ff0000", "#00ffff"]
|
---|
| 814 | color.harmonies("double-split-complementary").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000", "#00ff80", "#0080ff"]
|
---|
| 815 | color.harmonies("rectangle").map((c) => c.toHex()); // ["#ff0000", "#ffff00", "#00ffff", "#0000ff"]
|
---|
| 816 | color.harmonies("split-complementary").map((c) => c.toHex()); // ["#ff0000", "#00ff80", "#0080ff"]
|
---|
| 817 | color.harmonies("tetradic").map((c) => c.toHex()); // ["#ff0000", "#80ff00", "#00ffff", "#8000ff"]
|
---|
| 818 | color.harmonies("triadic").map((c) => c.toHex()); // ["#ff0000", "#00ff00", "#0000ff"]
|
---|
| 819 | ```
|
---|
| 820 |
|
---|
| 821 | </details>
|
---|
| 822 |
|
---|
| 823 | <details>
|
---|
| 824 | <summary><b><code>hwb</code> (HWB color model)</b> <i>0.8 KB</i></summary>
|
---|
| 825 |
|
---|
| 826 | Adds support of [Hue-Whiteness-Blackness](https://en.wikipedia.org/wiki/HWB_color_model) color model.
|
---|
| 827 |
|
---|
| 828 | ```js
|
---|
| 829 | import { colord, extend } from "colord";
|
---|
| 830 | import hwbPlugin from "colord/plugins/hwb";
|
---|
| 831 |
|
---|
| 832 | extend([hwbPlugin]);
|
---|
| 833 |
|
---|
| 834 | colord("#999966").toHwb(); // { h: 60, w: 40, b: 40, a: 1 }
|
---|
| 835 | colord("#003366").toHwbString(); // "hwb(210 0% 60%)"
|
---|
| 836 |
|
---|
| 837 | colord({ h: 60, w: 40, b: 40 }).toHex(); // "#999966"
|
---|
| 838 | colord("hwb(210 0% 60% / 50%)").toHex(); // "#00336680"
|
---|
| 839 | ```
|
---|
| 840 |
|
---|
| 841 | </details>
|
---|
| 842 |
|
---|
| 843 | <details>
|
---|
| 844 | <summary><b><code>lab</code> (CIE LAB color space)</b> <i>1.4 KB</i></summary>
|
---|
| 845 |
|
---|
| 846 | Adds support of [CIE LAB](https://en.wikipedia.org/wiki/CIELAB_color_space) color model. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).
|
---|
| 847 |
|
---|
| 848 | Also plugin provides `.delta` method for [perceived color difference calculations](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).
|
---|
| 849 |
|
---|
| 850 | ```js
|
---|
| 851 | import { colord, extend } from "colord";
|
---|
| 852 | import labPlugin from "colord/plugins/lab";
|
---|
| 853 |
|
---|
| 854 | extend([labPlugin]);
|
---|
| 855 |
|
---|
| 856 | colord({ l: 53.24, a: 80.09, b: 67.2 }).toHex(); // "#ff0000"
|
---|
| 857 | colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }
|
---|
| 858 |
|
---|
| 859 | colord("#afafaf").delta("#b4b4b4"); // 0.014
|
---|
| 860 | colord("#000000").delta("#ffffff"); // 1
|
---|
| 861 | ```
|
---|
| 862 |
|
---|
| 863 | </details>
|
---|
| 864 |
|
---|
| 865 | <details>
|
---|
| 866 | <summary><b><code>lch</code> (CIE LCH color space)</b> <i>1.3 KB</i></summary>
|
---|
| 867 |
|
---|
| 868 | Adds support of [CIE LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).
|
---|
| 869 |
|
---|
| 870 | ```js
|
---|
| 871 | import { colord, extend } from "colord";
|
---|
| 872 | import lchPlugin from "colord/plugins/lch";
|
---|
| 873 |
|
---|
| 874 | extend([lchPlugin]);
|
---|
| 875 |
|
---|
| 876 | colord({ l: 100, c: 0, h: 0 }).toHex(); // "#ffffff"
|
---|
| 877 | colord("lch(48.25% 30.07 196.38)").toHex(); // "#008080"
|
---|
| 878 |
|
---|
| 879 | colord("#646464").toLch(); // { l: 42.37, c: 0, h: 0, a: 1 }
|
---|
| 880 | colord("#646464").alpha(0.5).toLchString(); // "lch(42.37% 0 0 / 0.5)"
|
---|
| 881 | ```
|
---|
| 882 |
|
---|
| 883 | </details>
|
---|
| 884 |
|
---|
| 885 | <details>
|
---|
| 886 | <summary><b><code>mix</code> (Color mixing)</b> <i>0.96 KB</i></summary>
|
---|
| 887 |
|
---|
| 888 | A plugin adding a color mixing utilities.
|
---|
| 889 |
|
---|
| 890 | In contrast to other libraries that perform RGB values mixing, Colord mixes colors through [LAB color space](https://en.wikipedia.org/wiki/CIELAB_color_space). This approach produces better results and doesn't have the drawbacks the legacy way has.
|
---|
| 891 |
|
---|
| 892 | → [Online demo](https://3cg7o.csb.app/)
|
---|
| 893 |
|
---|
| 894 | ```js
|
---|
| 895 | import { colord, extend } from "colord";
|
---|
| 896 | import mixPlugin from "colord/plugins/mix";
|
---|
| 897 |
|
---|
| 898 | extend([mixPlugin]);
|
---|
| 899 |
|
---|
| 900 | colord("#ffffff").mix("#000000").toHex(); // "#777777"
|
---|
| 901 | colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
|
---|
| 902 | colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#e3c07e"
|
---|
| 903 | colord("#008080").mix("#808000", 0.35).toHex(); // "#50805d"
|
---|
| 904 | ```
|
---|
| 905 |
|
---|
| 906 | Also, the plugin provides special mixtures such as [tints, shades, and tones](https://en.wikipedia.org/wiki/Tints_and_shades):
|
---|
| 907 |
|
---|
| 908 | <div align="center">
|
---|
| 909 | <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d6/Tint-tone-shade.svg/320px-Tint-tone-shade.svg.png" alt="tints, shades, and tones mixtures" />
|
---|
| 910 | </div>
|
---|
| 911 |
|
---|
| 912 | ```js
|
---|
| 913 | const color = colord("#ff0000");
|
---|
| 914 | color.tints(3).map((c) => c.toHex()); // ["#ff0000", "#ff9f80", "#ffffff"];
|
---|
| 915 | color.shades(3).map((c) => c.toHex()); // ["#ff0000", "#7a1b0b", "#000000"];
|
---|
| 916 | color.tones(3).map((c) => c.toHex()); // ["#ff0000", "#c86147", "#808080"];
|
---|
| 917 | ```
|
---|
| 918 |
|
---|
| 919 | </details>
|
---|
| 920 |
|
---|
| 921 | <details>
|
---|
| 922 | <summary><b><code>names</code> (CSS color keywords)</b> <i>1.45 KB</i></summary>
|
---|
| 923 |
|
---|
| 924 | Provides options to convert a color into a [CSS color keyword](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords) and vice versa.
|
---|
| 925 |
|
---|
| 926 | ```js
|
---|
| 927 | import { colord, extend } from "colord";
|
---|
| 928 | import namesPlugin from "colord/plugins/names";
|
---|
| 929 |
|
---|
| 930 | extend([namesPlugin]);
|
---|
| 931 |
|
---|
| 932 | colord("tomato").toHex(); // "#ff6347"
|
---|
| 933 | colord("#00ffff").toName(); // "cyan"
|
---|
| 934 | colord("rgba(0, 0, 0, 0)").toName(); // "transparent"
|
---|
| 935 | colord("#fe0000").toName(); // undefined (the color is not specified in CSS specs)
|
---|
| 936 | colord("#fe0000").toName({ closest: true }); // "red" (closest color)
|
---|
| 937 | ```
|
---|
| 938 |
|
---|
| 939 | </details>
|
---|
| 940 |
|
---|
| 941 | <details>
|
---|
| 942 | <summary><b><code>xyz</code> (CIE XYZ color space)</b> <i>0.7 KB</i></summary>
|
---|
| 943 |
|
---|
| 944 | Adds support of [CIE XYZ](https://www.sttmedia.com/colormodel-xyz) color model. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).
|
---|
| 945 |
|
---|
| 946 | ```js
|
---|
| 947 | import { colord, extend } from "colord";
|
---|
| 948 | import xyzPlugin from "colord/plugins/xyz";
|
---|
| 949 |
|
---|
| 950 | extend([xyzPlugin]);
|
---|
| 951 |
|
---|
| 952 | colord("#ffffff").toXyz(); // { x: 95.047, y: 100, z: 108.883, a: 1 }
|
---|
| 953 | colord({ x: 0, y: 0, z: 0 }).toHex(); // "#000000"
|
---|
| 954 | ```
|
---|
| 955 |
|
---|
| 956 | </details>
|
---|
| 957 |
|
---|
| 958 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 959 |
|
---|
| 960 | ## Types
|
---|
| 961 |
|
---|
| 962 | **Colord** is written in strict TypeScript and ships with types in the library itself — no need for any other install. We provide everything you need in one tiny package.
|
---|
| 963 |
|
---|
| 964 | While not only typing its own functions and variables, **Colord** can also help you type yours. Depending on the color space you are using, you can also import and use the type that is associated with it.
|
---|
| 965 |
|
---|
| 966 | ```ts
|
---|
| 967 | import { RgbColor, RgbaColor, HslColor, HslaColor, HsvColor, HsvaColor } from "colord";
|
---|
| 968 |
|
---|
| 969 | const foo: HslColor = { h: 0, s: 0, l: 0 };
|
---|
| 970 | const bar: RgbColor = { r: 0, g: 0, v: 0 }; // ERROR
|
---|
| 971 | ```
|
---|
| 972 |
|
---|
| 973 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 974 |
|
---|
| 975 | ## Projects using Colord
|
---|
| 976 |
|
---|
| 977 | - [cssnano](https://github.com/cssnano/cssnano) — the most popular CSS minification tool
|
---|
| 978 | - [Resume.io](https://resume.io/) — online resume builder with over 12,000,000 users worldwide
|
---|
| 979 | - [Leva](https://github.com/pmndrs/leva) — open source extensible GUI panel made for React
|
---|
| 980 | - [Qui Max](https://github.com/Qvant-lab/qui-max) — Vue.js design system and component library
|
---|
| 981 | - and [thousands more](https://github.com/omgovich/colord/network/dependents)...
|
---|
| 982 |
|
---|
| 983 | <div><img src="assets/divider.png" width="838" alt="---" /></div>
|
---|
| 984 |
|
---|
| 985 | ## Roadmap
|
---|
| 986 |
|
---|
| 987 | - [x] Parse and convert Hex, RGB(A), HSL(A), HSV(A)
|
---|
| 988 | - [x] Saturate, desaturate, grayscale
|
---|
| 989 | - [x] Trim an input value
|
---|
| 990 | - [x] Clamp input numbers to resolve edge cases (e.g. `rgb(256, -1, 999, 2)`)
|
---|
| 991 | - [x] `brightness`, `isDark`, `isLight`
|
---|
| 992 | - [x] Set and get `alpha`
|
---|
| 993 | - [x] Plugin API
|
---|
| 994 | - [x] 4 and 8 digit Hex
|
---|
| 995 | - [x] `lighten`, `darken`
|
---|
| 996 | - [x] `invert`
|
---|
| 997 | - [x] CSS color names (via plugin)
|
---|
| 998 | - [x] A11y and contrast utils (via plugin)
|
---|
| 999 | - [x] XYZ color space (via plugin)
|
---|
| 1000 | - [x] [HWB](https://drafts.csswg.org/css-color/#the-hwb-notation) color space (via plugin)
|
---|
| 1001 | - [x] [LAB](https://www.w3.org/TR/css-color-4/#resolving-lab-lch-values) color space (via plugin)
|
---|
| 1002 | - [x] [LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space (via plugin)
|
---|
| 1003 | - [x] Mix colors (via plugin)
|
---|
| 1004 | - [x] CMYK color space (via plugin)
|
---|