color

immutable color conversion and manipulation with support for CSS color stri...

Colors
Qix-/colorcolor

README

color


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


  1. ``` js
  2. const color = Color('#7743CE').alpha(0.5).lighten(0.5);
  3. console.log(color.hsl().string());  // 'hsla(262, 59%, 81%, 0.5)'

  5. console.log(color.cmyk().round().array());  // [ 16, 25, 0, 8, 0.5 ]

  7. console.log(color.ansi256().object());  // { ansi256: 183, alpha: 0.5 }
  8. ```

Install

  1. ```console
  2. $ npm install color
  3. ```

Usage

  1. ``` js
  2. const Color = require('color');
  3. ```

Constructors

  1. ``` js
  2. const color = Color('rgb(255, 255, 255)')
  3. const color = Color({r: 255, g: 255, b: 255})
  4. const color = Color.rgb(255, 255, 255)
  5. const color = Color.rgb([255, 255, 255])
  6. ```

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

  1. ``` js
  2. color.hsl();
  3. ```
Convert a color to a different space (hsl(), cmyk(), etc.).

  1. ``` js
  2. color.object(); // {r: 255, g: 255, b: 255}
  3. ```
Get a hash of the color value. Reflects the color's current model (see above).

  1. ``` js
  2. color.rgb().array()  // [255, 255, 255]
  3. ```
Get an array of the values with array(). Reflects the color's current model (see above).

  1. ``` js
  2. color.rgbNumber() // 16777215 (0xffffff)
  3. ```
Get the rgb number value.

  1. ``` js
  2. color.hex() // #ffffff
  3. ```
Get the hex value. (NOTE: .hex() does not return alpha values; use .hexa() for an RGBA representation)

  1. ``` js
  2. color.red()       // 255
  3. ```
Get the value for an individual channel.

CSS Strings

  1. ``` js
  2. color.hsl().string()  // 'hsl(320, 50%, 100%)'
  3. ```

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

Luminosity

  1. ``` js
  2. color.luminosity();  // 0.412
  3. ```
The WCAG luminosity of the color. 0 is black, 1 is white.

  1. ``` js
  2. color.contrast(Color("blue"))  // 12
  3. ```
The WCAG contrast ratio to another color, from 1 (same color) to 21 (contrast b/w white and black).

  1. ``` js
  2. color.isLight();  // true
  3. color.isDark();   // false
  4. ```
Get whether the color is "light" or "dark", useful for deciding text color.

Manipulation

  1. ``` js
  2. color.negate()         // rgb(0, 100, 255) -> rgb(255, 155, 0)

  4. color.lighten(0.5)     // hsl(100, 50%, 50%) -> hsl(100, 50%, 75%)
  5. color.lighten(0.5)     // hsl(100, 50%, 0)   -> hsl(100, 50%, 0)
  6. color.darken(0.5)      // hsl(100, 50%, 50%) -> hsl(100, 50%, 25%)
  7. color.darken(0.5)      // hsl(100, 50%, 0)   -> hsl(100, 50%, 0)

  9. color.lightness(50)    // hsl(100, 50%, 10%) -> hsl(100, 50%, 50%)

  11. color.saturate(0.5)    // hsl(100, 50%, 50%) -> hsl(100, 75%, 50%)
  12. color.desaturate(0.5)  // hsl(100, 50%, 50%) -> hsl(100, 25%, 50%)
  13. color.grayscale()      // #5CBF54 -> #969696

  15. color.whiten(0.5)      // hwb(100, 50%, 50%) -> hwb(100, 75%, 50%)
  16. color.blacken(0.5)     // hwb(100, 50%, 50%) -> hwb(100, 50%, 75%)

  18. color.fade(0.5)     // rgba(10, 10, 10, 0.8) -> rgba(10, 10, 10, 0.4)
  19. color.opaquer(0.5)     // rgba(10, 10, 10, 0.8) -> rgba(10, 10, 10, 1.0)

  21. color.rotate(180)      // hsl(60, 20%, 20%) -> hsl(240, 20%, 20%)
  22. color.rotate(-90)      // hsl(60, 20%, 20%) -> hsl(330, 20%, 20%)

  24. color.mix(Color("yellow"))        // cyan -> rgb(128, 255, 128)
  25. color.mix(Color("yellow"), 0.3)   // cyan -> rgb(77, 255, 179)

  27. // chaining
  28. color.green(100).grayscale().lighten(0.6)
  29. ```

Propers

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