1 | # color
|
2 |
|
3 | > JavaScript library for immutable color conversion and manipulation with support for CSS color strings.
|
4 |
|
5 | ```js
|
6 | const color = Color('#7743CE').alpha(0.5).lighten(0.5);
|
7 | console.log(color.hsl().string()); // 'hsla(262, 59%, 81%, 0.5)'
|
8 |
|
9 | console.log(color.cmyk().round().array()); // [ 16, 25, 0, 8, 0.5 ]
|
10 |
|
11 | console.log(color.ansi256().object()); // { ansi256: 183, alpha: 0.5 }
|
12 | ```
|
13 |
|
14 | ## Install
|
15 | ```console
|
16 | $ npm install color
|
17 | ```
|
18 |
|
19 | ## Usage
|
20 | ```js
|
21 | const Color = require('color');
|
22 | ```
|
23 |
|
24 | ### Constructors
|
25 | ```js
|
26 | const color = Color('rgb(255, 255, 255)')
|
27 | const color = Color({r: 255, g: 255, b: 255})
|
28 | const color = Color.rgb(255, 255, 255)
|
29 | const color = Color.rgb([255, 255, 255])
|
30 | ```
|
31 |
|
32 | Set the values for individual channels with `alpha`, `red`, `green`, `blue`, `hue`, `saturationl` (hsl), `saturationv` (hsv), `lightness`, `whiteness`, `blackness`, `cyan`, `magenta`, `yellow`, `black`
|
33 |
|
34 | String constructors are handled by [color-string](https://www.npmjs.com/package/color-string)
|
35 |
|
36 | ### Getters
|
37 | ```js
|
38 | color.hsl();
|
39 | ```
|
40 | Convert a color to a different space (`hsl()`, `cmyk()`, etc.).
|
41 |
|
42 | ```js
|
43 | color.object(); // {r: 255, g: 255, b: 255}
|
44 | ```
|
45 | Get a hash of the color value. Reflects the color's current model (see above).
|
46 |
|
47 | ```js
|
48 | color.rgb().array() // [255, 255, 255]
|
49 | ```
|
50 | Get an array of the values with `array()`. Reflects the color's current model (see above).
|
51 |
|
52 | ```js
|
53 | color.rgbNumber() // 16777215 (0xffffff)
|
54 | ```
|
55 | Get the rgb number value.
|
56 |
|
57 | ```js
|
58 | color.hex() // #ffffff
|
59 | ```
|
60 | Get the hex value. (**NOTE:** `.hex()` does not return alpha values; use `.hexa()` for an RGBA representation)
|
61 |
|
62 | ```js
|
63 | color.red() // 255
|
64 | ```
|
65 | Get the value for an individual channel.
|
66 |
|
67 | ### CSS Strings
|
68 | ```js
|
69 | color.hsl().string() // 'hsl(320, 50%, 100%)'
|
70 | ```
|
71 |
|
72 | Calling `.string()` with a number rounds the numbers to that decimal place. It defaults to 1.
|
73 |
|
74 | ### Luminosity
|
75 | ```js
|
76 | color.luminosity(); // 0.412
|
77 | ```
|
78 | The [WCAG luminosity](http://www.w3.org/TR/WCAG20/#relativeluminancedef) of the color. 0 is black, 1 is white.
|
79 |
|
80 | ```js
|
81 | color.contrast(Color("blue")) // 12
|
82 | ```
|
83 | The [WCAG contrast ratio](http://www.w3.org/TR/WCAG20/#contrast-ratiodef) to another color, from 1 (same color) to 21 (contrast b/w white and black).
|
84 |
|
85 | ```js
|
86 | color.isLight(); // true
|
87 | color.isDark(); // false
|
88 | ```
|
89 | Get whether the color is "light" or "dark", useful for deciding text color.
|
90 |
|
91 | ### Manipulation
|
92 | ```js
|
93 | color.negate() // rgb(0, 100, 255) -> rgb(255, 155, 0)
|
94 |
|
95 | color.lighten(0.5) // hsl(100, 50%, 50%) -> hsl(100, 50%, 75%)
|
96 | color.lighten(0.5) // hsl(100, 50%, 0) -> hsl(100, 50%, 0)
|
97 | color.darken(0.5) // hsl(100, 50%, 50%) -> hsl(100, 50%, 25%)
|
98 | color.darken(0.5) // hsl(100, 50%, 0) -> hsl(100, 50%, 0)
|
99 |
|
100 | color.lightness(50) // hsl(100, 50%, 10%) -> hsl(100, 50%, 50%)
|
101 |
|
102 | color.saturate(0.5) // hsl(100, 50%, 50%) -> hsl(100, 75%, 50%)
|
103 | color.desaturate(0.5) // hsl(100, 50%, 50%) -> hsl(100, 25%, 50%)
|
104 | color.grayscale() // #5CBF54 -> #969696
|
105 |
|
106 | color.whiten(0.5) // hwb(100, 50%, 50%) -> hwb(100, 75%, 50%)
|
107 | color.blacken(0.5) // hwb(100, 50%, 50%) -> hwb(100, 50%, 75%)
|
108 |
|
109 | color.fade(0.5) // rgba(10, 10, 10, 0.8) -> rgba(10, 10, 10, 0.4)
|
110 | color.opaquer(0.5) // rgba(10, 10, 10, 0.8) -> rgba(10, 10, 10, 1.0)
|
111 |
|
112 | color.rotate(180) // hsl(60, 20%, 20%) -> hsl(240, 20%, 20%)
|
113 | color.rotate(-90) // hsl(60, 20%, 20%) -> hsl(330, 20%, 20%)
|
114 |
|
115 | color.mix(Color("yellow")) // cyan -> rgb(128, 255, 128)
|
116 | color.mix(Color("yellow"), 0.3) // cyan -> rgb(77, 255, 179)
|
117 |
|
118 | // chaining
|
119 | color.green(100).grayscale().lighten(0.6)
|
120 | ```
|
121 |
|
122 | ## Propers
|
123 | The API was inspired by [color-js](https://github.com/brehaut/color-js). Manipulation functions by CSS tools like Sass, LESS, and Stylus.
|