color

JavaScript library for immutable color conversion and manipulation with support for CSS color strings.

1const color = Color('#7743CE').alpha(0.5).lighten(0.5);
2console.log(color.hsl().string());  // 'hsla(262, 59%, 81%, 0.5)'
3
4console.log(color.cmyk().round().array());  // [ 16, 25, 0, 8, 0.5 ]
5
6console.log(color.ansi256().object());  // { ansi256: 183, alpha: 0.5 }

Install

1npm install color

Usage

1import Color from 'color';

Constructors

1// string constructor
2const color = Color('rgb(255, 255, 255)')                       // { model: 'rgb', color: [ 255, 255, 255 ], valpha: 1 }
3const color = Color('hsl(194, 53%, 79%)')                       // { model: 'hsl', color: [ 195, 53, 79 ], valpha: 1 }
4const color = Color('hsl(194, 53%, 79%, 0.5)')                  // { model: 'hsl', color: [ 195, 53, 79 ], valpha: 0.5 }
5const color = Color('#FF0000')                                  // { model: 'rgb', color: [ 255, 0, 0 ], valpha: 1 }
6const color = Color('#FF000033')                                // { model: 'rgb', color: [ 255, 0, 0 ], valpha: 0.2 }
7const color = Color('lightblue')                                // { model: 'rgb', color: [ 173, 216, 230 ], valpha: 1 }
8const color = Color('purple')                                   // { model: 'rgb', color: [ 128, 0, 128 ], valpha: 1 }
9
10// rgb
11const color = Color({r: 255, g: 255, b: 255})                   // { model: 'rgb', color: [ 255, 255, 255 ], valpha: 1 }
12const color = Color({r: 255, g: 255, b: 255, alpha: 0.5})       // { model: 'rgb', color: [ 255, 255, 255 ], valpha: 0.5 }
13const color = Color.rgb(255, 255, 255)                          // { model: 'rgb', color: [ 255, 255, 255 ], valpha: 1 }
14const color = Color.rgb(255, 255, 255, 0.5)                     // { model: 'rgb', color: [ 255, 255, 255 ], valpha: 0.5 }
15const color = Color.rgb(0xFF, 0x00, 0x00, 0.5)                  // { model: 'rgb', color: [ 255, 0, 0 ], valpha: 0.5 }
16const color = Color.rgb([255, 255, 255])                        // { model: 'rgb', color: [ 255, 255, 255 ], valpha: 1 }
17const color = Color.rgb([0xFF, 0x00, 0x00, 0.5])                // { model: 'rgb', color: [ 255, 0, 0 ], valpha: 0.5 }
18
19// hsl
20const color = Color({h: 194, s: 53, l: 79})                     // { model: 'hsl', color: [ 195, 53, 79 ], valpha: 1 }
21const color = Color({h: 194, s: 53, l: 79, alpha: 0.5})         // { model: 'hsl', color: [ 195, 53, 79 ], valpha: 0.5 }
22const color = Color.hsl(194, 53, 79)                            // { model: 'hsl', color: [ 195, 53, 79 ], valpha: 1 }
23
24// hsv
25const color = Color({h: 195, s: 25, v: 99})                     // { model: 'hsv', color: [ 195, 25, 99 ], valpha: 1 }
26const color = Color({h: 195, s: 25, v: 99, alpha: 0.5})         // { model: 'hsv', color: [ 195, 25, 99 ], valpha: 0.5 }
27const color = Color.hsv(195, 25, 99)                            // { model: 'hsv', color: [ 195, 25, 99 ], valpha: 1 }
28const color = Color.hsv([195, 25, 99])                          // { model: 'hsv', color: [ 195, 25, 99 ], valpha: 1 }
29
30// cmyk
31const color = Color({c: 0, m: 100, y: 100, k: 0})               // { model: 'cmyk', color: [ 0, 100, 100, 0 ], valpha: 1 }
32const color = Color({c: 0, m: 100, y: 100, k: 0, alpha: 0.5})   // { model: 'cmyk', color: [ 0, 100, 100, 0 ], valpha: 0.5 }
33const color = Color.cmyk(0, 100, 100, 0)                        // { model: 'cmyk', color: [ 0, 100, 100, 0 ], valpha: 1 }
34const color = Color.cmyk(0, 100, 100, 0, 0.5)                   // { model: 'cmyk', color: [ 0, 100, 100, 0 ], valpha: 0.5 }
35
36// hwb
37const color = Color({h: 180, w: 0, b: 0})                       // { model: 'hwb', color: [ 180, 0, 0 ], valpha: 1 }
38const color = Color.hwb(180, 0, 0)                              // { model: 'hwb', color: [ 180, 0, 0 ], valpha: 1 }
39
40// lch
41const color = Color({l: 53, c: 105, h: 40})                     // { model: 'lch', color: [ 53, 105, 40 ], valpha: 1 }
42const color = Color.lch(53, 105, 40)                            // { model: 'lch', color: [ 53, 105, 40 ], valpha: 1 }
43
44// lab
45const color = Color({l: 53, a: 80, b: 67})                      // { model: 'lab', color: [ 53, 80, 67 ], valpha: 1 }
46const color = Color.lab(53, 80, 67)                             // { model: 'lab', color: [ 53, 80, 67 ], valpha: 1 }
47
48// hcg
49const color = Color({h: 0, c: 100, g: 0})                       // { model: 'hcg', color: [ 0, 100, 0 ], valpha: 1 }
50const color = Color.hcg(0, 100, 0)                              // { model: 'hcg', color: [ 0, 100, 0 ], valpha: 1 }
51
52// ansi16
53const color = Color.ansi16(91)                                  // { model: 'ansi16', color: [ 91 ], valpha: 1 }
54const color = Color.ansi16(91, 0.5)                             // { model: 'ansi16', color: [ 91 ], valpha: 0.5 }
55
56// ansi256
57const color = Color.ansi256(196)                                // { model: 'ansi256', color: [ 196 ], valpha: 1 }
58const color = Color.ansi256(196, 0.5)                           // { model: 'ansi256', color: [ 196 ], valpha: 0.5 }
59
60// apple
61const color = Color.apple(65535, 65535, 65535)                  // { model: 'apple', color: [ 65535, 65535, 65535 ], valpha: 1 }
62const color = Color.apple([65535, 65535, 65535])                // { model: 'apple', color: [ 65535, 65535, 65535 ], valpha: 1 }
63
64

Set the values for individual channels with alpha, red, green, blue, hue, saturationl (hsl), saturationv (hsv), lightness, whiteness, blackness, cyan, magenta, yellow, black

String constructors are handled by color-string

Getters

1color.hsl()

Convert a color to a different space (hsl(), cmyk(), etc.).

1color.object() // {r: 255, g: 255, b: 255}

Get a hash of the color value. Reflects the color's current model (see above).

1color.rgb().array() // [255, 255, 255]

Get an array of the values with array(). Reflects the color's current model (see above).

1color.rgbNumber() // 16777215 (0xffffff)

Get the rgb number value.

1color.hex() // #ffffff

Get the hex value. (NOTE: .hex() does not return alpha values; use .hexa() for an RGBA representation)

1color.red() // 255

Get the value for an individual channel.

CSS Strings

1color.hsl().string() // 'hsl(320, 50%, 100%)'

Calling .string() with a number rounds the numbers to that decimal place. It defaults to 1.

Luminosity

1color.luminosity(); // 0.412

The WCAG luminosity of the color. 0 is black, 1 is white.

1color.contrast(Color("blue")) // 12

The WCAG contrast ratio to another color, from 1 (same color) to 21 (contrast b/w white and black).

1color.isLight()  // true
2color.isDark()   // false

Get whether the color is "light" or "dark", useful for deciding text color.

Manipulation

1color.negate()         // rgb(0, 100, 255) -> rgb(255, 155, 0)
2
3color.lighten(0.5)     // hsl(100, 50%, 50%) -> hsl(100, 50%, 75%)
4color.lighten(0.5)     // hsl(100, 50%, 0)   -> hsl(100, 50%, 0)
5color.darken(0.5)      // hsl(100, 50%, 50%) -> hsl(100, 50%, 25%)
6color.darken(0.5)      // hsl(100, 50%, 0)   -> hsl(100, 50%, 0)
7
8color.lightness(50)    // hsl(100, 50%, 10%) -> hsl(100, 50%, 50%)
9
10color.saturate(0.5)    // hsl(100, 50%, 50%) -> hsl(100, 75%, 50%)
11color.desaturate(0.5)  // hsl(100, 50%, 50%) -> hsl(100, 25%, 50%)
12color.grayscale()      // #5CBF54 -> #969696
13
14color.whiten(0.5)      // hwb(100, 50%, 50%) -> hwb(100, 75%, 50%)
15color.blacken(0.5)     // hwb(100, 50%, 50%) -> hwb(100, 50%, 75%)
16
17color.fade(0.5)        // rgba(10, 10, 10, 0.8) -> rgba(10, 10, 10, 0.4)
18color.opaquer(0.5)     // rgba(10, 10, 10, 0.8) -> rgba(10, 10, 10, 1.0)
19
20color.rotate(180)      // hsl(60, 20%, 20%) -> hsl(240, 20%, 20%)
21color.rotate(-90)      // hsl(60, 20%, 20%) -> hsl(330, 20%, 20%)
22
23color.mix(Color("yellow"))        // cyan -> rgb(128, 255, 128)
24color.mix(Color("yellow"), 0.3)   // cyan -> rgb(77, 255, 179)
25
26// chaining
27color.green(100).grayscale().lighten(0.6)

Propers

The API was inspired by color-js. Manipulation functions by CSS tools like Sass, LESS, and Stylus.