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
• Alpha
• Hue
• Lightness
• Mix
• Saturation

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).

License

MIT License 2017 © Chad Donohue