Polychrome NPM

`polychrome`

A small ~2kB (gzipped) library for parsing and manipulating colors

Installation

feel free to replace yarn add with npm install
$> yarn add polychrome

Usage

// using ES6 modules
import polychrome from "polychrome";

// using CommonJS modules
const polychrome = require("polychrome");

// Make a polychrome color from hex, rgb(a), and hsl(a) strings
const red = polychrome("#F00");

// Get a string representation of a polychrome color in other formats
red.rgb() // "rgb(255,0,0)"

// Manipulate polychrome colors
const darkerRed = red.darken(20); // (pass in an integer percentage)
darkerRed.hsl() // "hsl(0,100%,40%)"

// Chain polychrome methods together before outputting
polychrome("#F00").darken(20).fadeOut(60).rgb() // "rgba(204,0,0,0.4)"

API Reference

Polychrome Object

polychrome(colorString)

colorString can be a hex (3 or 6 digit), rgb(a), or hsl(a) string. Returns a polychrome object.

A polychrome object consists of the following properties:

rHex - 2 character hex string representation of the red color channel
gHex - 2 character hex string representation of the green color channel
bHex - 2 character hex string representation of the blue color channel
r - value of the red color channel 0 - 255
g - value of the green color channel 0 - 255
b - value of the blue color channel 0 - 255
h - hue of the color 0 - 360
s - saturation of the color 0 - 100
l - lightness of the color 0 - 100
luma - luma value of the color 0 - 255

In addition to the above properties, the following methods are available to a polychrome for outputting CSS color strings:

.hex() - returns a 6-digit hexadecimal CSS compatible color string
```
polychrome("rgb(0, 0, 0)").hex() // "#000000"
```

.rgb() - returns an rgb(a) CSS compatible color string

// rgba will be used if an alpha value exists
polychrome("#000").rgb()           // "rgb(0,0,0)"
polychrome("#000").fadeOut(60).rgb() // "rgba(0,0,0,.4)"

.hsl() - returns an hsl(a) CSS compatible color string

// hsla will be used if an alpha value exists
polychrome("#000").hsl()           // "hsl(0,0%,0%)"
polychrome("#000").fadeOut(60).hsl() // "hsla(0,0%,0%,.4)"

Alpha

.setAlpha(value)
Returns a polychrome with an alpha value absolutely set to value. No change occurs if value is omitted.
.fadeIn(percentage)
Returns a polychrome faded in by percentage. Default 50 if no percentage is passed in.
.fadeOut(percentage)
Returns a polychrome faded out by percentage. Default 50 if no percentage is passed in.

Contrast

.contrast(dark, light)
Checks luma value of polychrome and returns dark or light polychrome depending on the contrast level. If a contrast ratio of at least 4.5:1 is not met, the dark/light colors will be darkened / lightened until a valid ratio is met.
```
polychrome("#000").contrast().rgb() // "rgb(255,255,255)"

polychrome("#DDD").contrast("#333", "#EEE").hex() // "#333333"
```
dark and light can be a String or polychrome. They default to black (#000) and white (#FFF) if params are not passed in.

Hue

.setHue(value)
Returns a polychrome with a hue value absolutely set to value. No change occurs if value is omitted.
.spin(degrees)
Returns a polychrome with a hue value rotated degrees. Can be a positive or negative degree value. When bounds of [0 - 360] are reached, hue will continue in a circular fashion until it has been spun the full amount.
.complimentary()
Returns a polychrome with a hue value rotated 180 degrees. Shorthand for .spin(180).

Lightness

.setLightness(value)
Returns a polychrome with a lightness value absolutely set to value. No change occurs if value is omitted.
.lighten(percentage)
Returns a polychrome lightened by percentage. Default 10 if no percentage is passed in.

.darken(percentage)
Returns a polychrome darkened by percentage. Default 10 if no percentage is passed in.

Mix

.mix(otherColor)
Returns a polychrome mixed with otherColor. otherColor can be another polychrome or a color string that will be parsed.
.tint()
Returns a polychrome mixed with white (#FFFFFF). Shorthand for .mix("#FFFFFF").
.shade()
Returns a polychrome mixed with black (#000000). Shorthand for .mix("#000000").

Saturation

.setSaturation(value)
Returns a polychrome with a saturation value absolutely set to value. No change occurs if value is omitted.
.saturate(percentage)
Returns a polychrome saturated by percentage. Default 10 if no percentage is passed in.
.desaturate(percentage)
Returns a polychrome desaturated by percentage. Default 10 if no percentage is passed in.
.grayscale()
Returns a polychrome with saturation set to 0. Shorthand for .setSaturation(0).