source: trip-planner-front/node_modules/colord/README.md

Last change on this file was e29cc2e, checked in by Ema <ema_spirova@…>, 3 years ago

primeNG components

  • Property mode set to 100644
File size: 37.5 KB
Line 
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
54The 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```
61npm i colord
62```
63
64```js
65import { colord } from "colord";
66
67colord("#ff0000").grayscale().alpha(0.25).toRgbString(); // "rgba(128, 128, 128, 0.25)"
68colord("rgb(192, 192, 192)").isLight(); // true
69colord("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
96Parses 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
99import { colord } from "colord";
100
101// String input examples
102colord("#FFF");
103colord("#ffffff");
104colord("#ffffffff");
105colord("rgb(255, 255, 255)");
106colord("rgba(255, 255, 255, 0.5)");
107colord("rgba(100% 100% 100% / 50%)");
108colord("hsl(90, 100%, 100%)");
109colord("hsla(90, 100%, 100%, 0.5)");
110colord("hsla(90deg 100% 100% / 50%)");
111colord("tomato"); // requires "names" plugin
112
113// Object input examples
114colord({ r: 255, g: 255, b: 255 });
115colord({ r: 255, g: 255, b: 255, a: 1 });
116colord({ h: 360, s: 100, l: 100 });
117colord({ h: 360, s: 100, l: 100, a: 1 });
118colord({ h: 360, s: 100, v: 100 });
119colord({ h: 360, s: 100, v: 100, a: 1 });
120```
121
122Check 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
129Returns a color model name for the input passed to the function. Uses the same parsing system as `colord` function.
130
131```js
132import { getFormat } from "colord";
133
134getFormat("#aabbcc"); // "hex"
135getFormat({ r: 13, g: 237, b: 162, a: 0.5 }); // "rgb"
136getFormat("hsl(180deg, 50%, 50%)"); // "hsl"
137getFormat("WUT?"); // undefined
138```
139
140</details>
141
142### Color conversion
143
144<details>
145 <summary><b><code>.toHex()</code></b></summary>
146
147Returns 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
150colord("rgb(0, 255, 0)").toHex(); // "#00ff00"
151colord({ h: 300, s: 100, l: 50 }).toHex(); // "#ff00ff"
152colord({ 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
161colord("#ff0000").toRgb(); // { r: 255, g: 0, b: 0, a: 1 }
162colord({ 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
171colord("#ff0000").toRgbString(); // "rgb(255, 0, 0)"
172colord({ 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
180Converts a color to [HSL color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and returns an object.
181
182```js
183colord("#ffff00").toHsl(); // { h: 60, s: 100, l: 50, a: 1 }
184colord("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
192Converts 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
195colord("#ffff00").toHslString(); // "hsl(60, 100%, 50%)"
196colord("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
204Converts a color to [HSV color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and returns an object.
205
206```js
207colord("#ffff00").toHsv(); // { h: 60, s: 100, v: 100, a: 1 }
208colord("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
216Converts 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
219import { colord, extend } from "colord";
220import namesPlugin from "colord/plugins/names";
221
222extend([namesPlugin]);
223
224colord("#ff6347").toName(); // "tomato"
225colord("#00ffff").toName(); // "cyan"
226colord("rgba(0, 0, 0, 0)").toName(); // "transparent"
227
228colord("#fe0000").toName(); // undefined (the color is not specified in CSS specs)
229colord("#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
237Converts a color to [CMYK](https://en.wikipedia.org/wiki/CMYK_color_model) color space.
238
239```js
240import { colord, extend } from "colord";
241import cmykPlugin from "colord/plugins/cmyk";
242
243extend([cmykPlugin]);
244
245colord("#ffffff").toCmyk(); // { c: 0, m: 0, y: 0, k: 0, a: 1 }
246colord("#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
254Converts a color to color space.
255
256Converts 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
259import { colord, extend } from "colord";
260import cmykPlugin from "colord/plugins/cmyk";
261
262extend([cmykPlugin]);
263
264colord("#99ffff").toCmykString(); // "device-cmyk(40% 0% 0% 0%)"
265colord("#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
273Converts a color to [HWB (Hue-Whiteness-Blackness)](https://en.wikipedia.org/wiki/HWB_color_model) color space.
274
275```js
276import { colord, extend } from "colord";
277import hwbPlugin from "colord/plugins/hwb";
278
279extend([hwbPlugin]);
280
281colord("#ffffff").toHwb(); // { h: 0, w: 100, b: 0, a: 1 }
282colord("#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
290Converts 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
293import { colord, extend } from "colord";
294import hwbPlugin from "colord/plugins/hwb";
295
296extend([hwbPlugin]);
297
298colord("#999966").toHwbString(); // "hwb(60 40% 40%)"
299colord("#99ffff").toHwbString(); // "hwb(180 60% 0%)"
300colord("#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
308Converts 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
311import { colord, extend } from "colord";
312import labPlugin from "colord/plugins/lab";
313
314extend([labPlugin]);
315
316colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }
317colord("#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
325Converts 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
328import { colord, extend } from "colord";
329import lchPlugin from "colord/plugins/lch";
330
331extend([lchPlugin]);
332
333colord("#ffffff").toLch(); // { l: 100, c: 0, h: 0, a: 1 }
334colord("#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
342Converts 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
345import { colord, extend } from "colord";
346import lchPlugin from "colord/plugins/lch";
347
348extend([lchPlugin]);
349
350colord("#ffffff").toLchString(); // "lch(100% 0 0)"
351colord("#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
359Converts 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
362import { colord, extend } from "colord";
363import xyzPlugin from "colord/plugins/xyz";
364
365extend([xyzPlugin]);
366
367colord("#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
377Changes the alpha channel value and returns a new `Colord` instance.
378
379```js
380colord("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
388Creates a new `Colord` instance containing an inverted (opposite) version of the color.
389
390```js
391colord("#ffffff").invert().toHex(); // "#000000"
392colord("#aabbcc").invert().toHex(); // "#554433"
393```
394
395</details>
396
397<details>
398 <summary><b><code>.saturate(amount = 0.1)</code></b></summary>
399
400Increases the [HSL saturation](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
401
402```js
403colord("#bf4040").saturate(0.25).toHex(); // "#df2020"
404colord("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
412Decreases the [HSL saturation](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
413
414```js
415colord("#df2020").saturate(0.25).toHex(); // "#bf4040"
416colord("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
424Makes a gray color with the same lightness as a source color. Same as calling `desaturate(1)`.
425
426```js
427colord("#bf4040").grayscale().toHex(); // "#808080"
428colord("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
436Increases the [HSL lightness](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
437
438```js
439colord("#000000").lighten(0.5).toHex(); // "#808080"
440colord("#223344").lighten(0.3).toHex(); // "#5580aa"
441colord("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
449Decreases the [HSL lightness](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.
450
451```js
452colord("#ffffff").darken(0.5).toHex(); // "#808080"
453colord("#5580aa").darken(0.3).toHex(); // "#223344"
454colord("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
462Changes the hue value and returns a new `Colord` instance.
463
464```js
465colord("hsl(90, 50%, 50%)").hue(180).toHslString(); // "hsl(180, 50%, 50%)"
466colord("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
474Increases the [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV) hue value of a color by the given amount.
475
476```js
477colord("hsl(90, 50%, 50%)").rotate(90).toHslString(); // "hsl(180, 50%, 50%)"
478colord("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
486Produces a mixture of two colors and returns the result of mixing them (new Colord instance).
487
488In 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
493import { colord, extend } from "colord";
494import mixPlugin from "colord/plugins/mix";
495
496extend([mixPlugin]);
497
498colord("#ffffff").mix("#000000").toHex(); // "#777777"
499colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
500colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#e3c07e"
501colord("#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
509Provides 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
512import { colord, extend } from "colord";
513import mixPlugin from "colord/plugins/mix";
514
515extend([mixPlugin]);
516
517const color = colord("#ff0000");
518color.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
526Provides 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
529import { colord, extend } from "colord";
530import mixPlugin from "colord/plugins/mix";
531
532extend([mixPlugin]);
533
534const color = colord("#ff0000");
535color.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
543Provides 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
546import { colord, extend } from "colord";
547import mixPlugin from "colord/plugins/mix";
548
549extend([mixPlugin]);
550
551const color = colord("#ff0000");
552color.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
560Provides functionality to generate [harmony colors](<https://en.wikipedia.org/wiki/Harmony_(color)>). Returns an array of `Colord` instances.
561
562```js
563import { colord, extend } from "colord";
564import harmoniesPlugin from "colord/plugins/harmonies";
565
566extend([harmoniesPlugin]);
567
568const color = colord("#ff0000");
569color.harmonies("analogous").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000"]
570color.harmonies("complementary").map((c) => c.toHex()); // ["#ff0000", "#00ffff"]
571color.harmonies("double-split-complementary").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000", "#00ff80", "#0080ff"]
572color.harmonies("rectangle").map((c) => c.toHex()); // ["#ff0000", "#ffff00", "#00ffff", "#0000ff"]
573color.harmonies("split-complementary").map((c) => c.toHex()); // ["#ff0000", "#00ff80", "#0080ff"]
574color.harmonies("tetradic").map((c) => c.toHex()); // ["#ff0000", "#80ff00", "#00ffff", "#8000ff"]
575color.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
585Returns a boolean indicating whether or not an input has been parsed successfully.
586Note: If parsing is unsuccessful, Colord defaults to black (does not throws an error).
587
588```js
589colord("#ffffff").isValid(); // true
590colord("#wwuutt").isValid(); // false
591colord("abracadabra").isValid(); // false
592colord({ r: 0, g: 0, b: 0 }).isValid(); // true
593colord({ 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
601Determines whether two values are the same color.
602
603```js
604colord("#000000").isEqual("rgb(0, 0, 0)"); // true
605colord("#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
614colord("#ffffff").alpha(); // 1
615colord("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
624colord("hsl(90, 50%, 50%)").hue(); // 90
625colord("hsl(-10, 50%, 50%)").hue(); // 350
626```
627
628</details>
629
630<details>
631 <summary><b><code>.brightness()</code></b></summary>
632
633Returns 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
636colord("#000000").brightness(); // 0
637colord("#808080").brightness(); // 0.5
638colord("#ffffff").brightness(); // 1
639```
640
641</details>
642
643<details>
644 <summary><b><code>.isLight()</code></b></summary>
645
646Same as calling `brightness() >= 0.5`.
647
648```js
649colord("#111111").isLight(); // false
650colord("#aabbcc").isLight(); // true
651colord("#ffffff").isLight(); // true
652```
653
654</details>
655
656<details>
657 <summary><b><code>.isDark()</code></b></summary>
658
659Same as calling `brightness() < 0.5`.
660
661```js
662colord("#111111").isDark(); // true
663colord("#aabbcc").isDark(); // false
664colord("#ffffff").isDark(); // false
665```
666
667</details>
668
669<details>
670 <summary><b><code>.luminance()</code></b> (<b>a11y</b> plugin)</summary>
671
672Returns 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
675colord("#000000").luminance(); // 0
676colord("#808080").luminance(); // 0.22
677colord("#ccddee").luminance(); // 0.71
678colord("#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
686Calculates 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
689colord("#000000").contrast(); // 21 (black on white)
690colord("#ffffff").contrast("#000000"); // 21 (white on black)
691colord("#777777").contrast(); // 4.47 (gray on white)
692colord("#ff0000").contrast(); // 3.99 (red on white)
693colord("#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
701Checks 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
704colord("#000000").isReadable(); // true (normal black text on white bg conforms to WCAG AA)
705colord("#777777").isReadable(); // false (normal gray text on white bg conforms to WCAG AA)
706colord("#ffffff").isReadable("#000000"); // true (normal white text on black bg conforms to WCAG AA)
707colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
708colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
709colord("#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
717Calculates the perceived color difference between two colors.
718The difference calculated according to [Delta E2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).
719The return value is `0` if the colors are equal, `1` if they are entirely different.
720
721```js
722colord("#3296fa").delta("#197dc8"); // 0.099
723colord("#faf0c8").delta("#ffffff"); // 0.148
724colord("#afafaf").delta("#b4b4b4"); // 0.014
725colord("#000000").delta("#ffffff"); // 1
726```
727
728</details>
729
730### Color utilities
731
732<details>
733 <summary><b><code>random()</code></b></summary>
734
735Returns a new Colord instance with a random color value inside.
736
737```js
738import { random } from "colord";
739
740random().toHex(); // "#01c8ec"
741random().alpha(0.5).toRgb(); // { r: 13, g: 237, b: 162, a: 0.5 }
742```
743
744</details>
745
746<details>
747 <summary><b><code>.minify(options?)</code></b></summary>
748
749Converts a color to its shortest string representation.
750
751```js
752import { colord, extend } from "colord";
753import minifyPlugin from "colord/plugins/minify";
754
755extend([minifyPlugin]);
756
757colord("black").minify(); // "#000"
758colord("#112233").minify(); // "#123"
759colord("darkgray").minify(); // "#a9a9a9"
760colord("rgba(170,170,170,0.4)").minify(); // "hsla(0,0%,67%,.4)"
761colord("rgba(170,170,170,0.4)").minify({ alphaHex: true }); // "#aaa6"
762```
763
764| Option | Default | Description |
765| ------------- | ------- | ------------------------------------------------------------ |
766| `hex` | `true` | Enable `#rrggbb` and `#rgb` notations |
767| `alphaHex` | `false` | Enable `#rrggbbaa` and `#rgba` notations |
768| `rgb` | `true` | Enable `rgb()` and `rgba()` functional notations |
769| `hsl` | `true` | Enable `hsl()` and `hsla()` functional notations |
770| `name` | `false` | Enable CSS color keywords. Requires `names` plugin installed |
771| `transparent` | `false` | Enable `"transparent"` color keyword |
772
773</details>
774
775<div><img src="assets/divider.png" width="838" alt="---" /></div>
776
777## Plugins
778
779**Colord** has a built-in plugin system that allows new features and functionality to be easily added.
780
781<details>
782 <summary><b><code>a11y</code> (Accessibility)</b> <i>0.38 KB</i></summary>
783
784Adds accessibility and color contrast utilities working according to [Web Content Accessibility Guidelines 2.0](https://www.w3.org/TR/WCAG20/).
785
786```js
787import { colord, extend } from "colord";
788import a11yPlugin from "colord/plugins/a11y";
789
790extend([a11yPlugin]);
791
792colord("#000000").luminance(); // 0
793colord("#ccddee").luminance(); // 0.71
794colord("#ffffff").luminance(); // 1
795
796colord("#000000").contrast(); // 21 (black on white)
797colord("#ffffff").contrast("#000000"); // 21 (white on black)
798colord("#0000ff").contrast("#ff000"); // 2.14 (blue on red)
799
800colord("#000000").isReadable(); // true (black on white)
801colord("#ffffff").isReadable("#000000"); // true (white on black)
802colord("#777777").isReadable(); // false (gray on white)
803colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
804colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
805colord("#e60000").isReadable("#ffff47", { level: "AAA", size: "large" }); // true (large red text on yellow bg conforms to WCAG AAA)
806```
807
808</details>
809
810<details>
811 <summary><b><code>cmyk</code> (CMYK color space)</b> <i>0.6 KB</i></summary>
812
813Adds support of [CMYK](https://www.sttmedia.com/colormodel-cmyk) color model.
814
815```js
816import { colord, extend } from "colord";
817import cmykPlugin from "colord/plugins/cmyk";
818
819extend([cmykPlugin]);
820
821colord("#ffffff").toCmyk(); // { c: 0, m: 0, y: 0, k: 0, a: 1 }
822colord("#999966").toCmykString(); // "device-cmyk(0% 0% 33% 40%)"
823colord({ c: 0, m: 0, y: 0, k: 100, a: 1 }).toHex(); // "#000000"
824colord("device-cmyk(0% 61% 72% 0% / 50%)").toHex(); // "#ff634780"
825```
826
827</details>
828
829<details>
830 <summary><b><code>harmonies</code> (Color harmonies)</b> <i>0.15 KB</i></summary>
831
832Provides functionality to generate [harmony colors](<https://en.wikipedia.org/wiki/Harmony_(color)>).
833
834```js
835import { colord, extend } from "colord";
836import harmonies from "colord/plugins/harmonies";
837
838extend([harmonies]);
839
840const color = colord("#ff0000");
841color.harmonies("analogous").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000"]
842color.harmonies("complementary").map((c) => c.toHex()); // ["#ff0000", "#00ffff"]
843color.harmonies("double-split-complementary").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000", "#00ff80", "#0080ff"]
844color.harmonies("rectangle").map((c) => c.toHex()); // ["#ff0000", "#ffff00", "#00ffff", "#0000ff"]
845color.harmonies("split-complementary").map((c) => c.toHex()); // ["#ff0000", "#00ff80", "#0080ff"]
846color.harmonies("tetradic").map((c) => c.toHex()); // ["#ff0000", "#80ff00", "#00ffff", "#8000ff"]
847color.harmonies("triadic").map((c) => c.toHex()); // ["#ff0000", "#00ff00", "#0000ff"]
848```
849
850</details>
851
852<details>
853 <summary><b><code>hwb</code> (HWB color model)</b> <i>0.8 KB</i></summary>
854
855Adds support of [Hue-Whiteness-Blackness](https://en.wikipedia.org/wiki/HWB_color_model) color model.
856
857```js
858import { colord, extend } from "colord";
859import hwbPlugin from "colord/plugins/hwb";
860
861extend([hwbPlugin]);
862
863colord("#999966").toHwb(); // { h: 60, w: 40, b: 40, a: 1 }
864colord("#003366").toHwbString(); // "hwb(210 0% 60%)"
865
866colord({ h: 60, w: 40, b: 40 }).toHex(); // "#999966"
867colord("hwb(210 0% 60% / 50%)").toHex(); // "#00336680"
868```
869
870</details>
871
872<details>
873 <summary><b><code>lab</code> (CIE LAB color space)</b> <i>1.4 KB</i></summary>
874
875Adds 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).
876
877Also plugin provides `.delta` method for [perceived color difference calculations](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).
878
879```js
880import { colord, extend } from "colord";
881import labPlugin from "colord/plugins/lab";
882
883extend([labPlugin]);
884
885colord({ l: 53.24, a: 80.09, b: 67.2 }).toHex(); // "#ff0000"
886colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }
887
888colord("#afafaf").delta("#b4b4b4"); // 0.014
889colord("#000000").delta("#ffffff"); // 1
890```
891
892</details>
893
894<details>
895 <summary><b><code>lch</code> (CIE LCH color space)</b> <i>1.3 KB</i></summary>
896
897Adds 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).
898
899```js
900import { colord, extend } from "colord";
901import lchPlugin from "colord/plugins/lch";
902
903extend([lchPlugin]);
904
905colord({ l: 100, c: 0, h: 0 }).toHex(); // "#ffffff"
906colord("lch(48.25% 30.07 196.38)").toHex(); // "#008080"
907
908colord("#646464").toLch(); // { l: 42.37, c: 0, h: 0, a: 1 }
909colord("#646464").alpha(0.5).toLchString(); // "lch(42.37% 0 0 / 0.5)"
910```
911
912</details>
913
914<details>
915 <summary><b><code>minify</code> (Color string minification)</b> <i>0.5 KB</i></summary>
916
917A plugin adding color string minification utilities.
918
919```js
920import { colord, extend } from "colord";
921import minifyPlugin from "colord/plugins/minify";
922
923extend([minifyPlugin]);
924
925colord("black").minify(); // "#000"
926colord("#112233").minify(); // "#123"
927colord("darkgray").minify(); // "#a9a9a9"
928colord("rgba(170,170,170,0.4)").minify(); // "hsla(0,0%,67%,.4)"
929colord("rgba(170,170,170,0.4)").minify({ alphaHex: true }); // "#aaa6"
930```
931
932</details>
933
934<details>
935 <summary><b><code>mix</code> (Color mixing)</b> <i>0.96 KB</i></summary>
936
937A plugin adding color mixing utilities.
938
939In 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.
940
941→ [Online demo](https://3cg7o.csb.app/)
942
943```js
944import { colord, extend } from "colord";
945import mixPlugin from "colord/plugins/mix";
946
947extend([mixPlugin]);
948
949colord("#ffffff").mix("#000000").toHex(); // "#777777"
950colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
951colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#e3c07e"
952colord("#008080").mix("#808000", 0.35).toHex(); // "#50805d"
953```
954
955Also, the plugin provides special mixtures such as [tints, shades, and tones](https://en.wikipedia.org/wiki/Tints_and_shades):
956
957<div align="center">
958<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" />
959</div>
960
961```js
962const color = colord("#ff0000");
963color.tints(3).map((c) => c.toHex()); // ["#ff0000", "#ff9f80", "#ffffff"];
964color.shades(3).map((c) => c.toHex()); // ["#ff0000", "#7a1b0b", "#000000"];
965color.tones(3).map((c) => c.toHex()); // ["#ff0000", "#c86147", "#808080"];
966```
967
968</details>
969
970<details>
971 <summary><b><code>names</code> (CSS color keywords)</b> <i>1.45 KB</i></summary>
972
973Provides 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.
974
975```js
976import { colord, extend } from "colord";
977import namesPlugin from "colord/plugins/names";
978
979extend([namesPlugin]);
980
981colord("tomato").toHex(); // "#ff6347"
982colord("#00ffff").toName(); // "cyan"
983colord("rgba(0, 0, 0, 0)").toName(); // "transparent"
984colord("#fe0000").toName(); // undefined (the color is not specified in CSS specs)
985colord("#fe0000").toName({ closest: true }); // "red" (closest color)
986```
987
988</details>
989
990<details>
991 <summary><b><code>xyz</code> (CIE XYZ color space)</b> <i>0.7 KB</i></summary>
992
993Adds 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).
994
995```js
996import { colord, extend } from "colord";
997import xyzPlugin from "colord/plugins/xyz";
998
999extend([xyzPlugin]);
1000
1001colord("#ffffff").toXyz(); // { x: 95.047, y: 100, z: 108.883, a: 1 }
1002colord({ x: 0, y: 0, z: 0 }).toHex(); // "#000000"
1003```
1004
1005</details>
1006
1007<div><img src="assets/divider.png" width="838" alt="---" /></div>
1008
1009## Types
1010
1011**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.
1012
1013While 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.
1014
1015```ts
1016import { RgbColor, RgbaColor, HslColor, HslaColor, HsvColor, HsvaColor } from "colord";
1017
1018const foo: HslColor = { h: 0, s: 0, l: 0 };
1019const bar: RgbColor = { r: 0, g: 0, v: 0 }; // ERROR
1020```
1021
1022<div><img src="assets/divider.png" width="838" alt="---" /></div>
1023
1024## Projects using Colord
1025
1026- [cssnano](https://github.com/cssnano/cssnano) — the most popular CSS minification tool
1027- [Resume.io](https://resume.io/) — online resume builder with over 12,000,000 users worldwide
1028- [Leva](https://github.com/pmndrs/leva) — open source extensible GUI panel made for React
1029- [Qui Max](https://github.com/Qvant-lab/qui-max) — Vue.js design system and component library
1030- and [thousands more](https://github.com/omgovich/colord/network/dependents)...
1031
1032<div><img src="assets/divider.png" width="838" alt="---" /></div>
1033
1034## Roadmap
1035
1036- [x] Parse and convert Hex, RGB(A), HSL(A), HSV(A)
1037- [x] Saturate, desaturate, grayscale
1038- [x] Trim an input value
1039- [x] Clamp input numbers to resolve edge cases (e.g. `rgb(256, -1, 999, 2)`)
1040- [x] `brightness`, `isDark`, `isLight`
1041- [x] Set and get `alpha`
1042- [x] Plugin API
1043- [x] 4 and 8 digit Hex
1044- [x] `lighten`, `darken`
1045- [x] `invert`
1046- [x] CSS color names (via plugin)
1047- [x] A11y and contrast utils (via plugin)
1048- [x] XYZ color space (via plugin)
1049- [x] [HWB](https://drafts.csswg.org/css-color/#the-hwb-notation) color space (via plugin)
1050- [x] [LAB](https://www.w3.org/TR/css-color-4/#resolving-lab-lch-values) color space (via plugin)
1051- [x] [LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space (via plugin)
1052- [x] Mix colors (via plugin)
1053- [x] CMYK color space (via plugin)
Note: See TracBrowser for help on using the repository browser.