Skip to content
🎨 Easy color manipulation in ~2kb (gzipped)
TypeScript JavaScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
images
src
test
.babelrc
.eslintrc
.gitignore
.npmignore
.nvmrc
LICENSE
README.md
package.json
rollup.config.js
yarn.lock

README.md

polychrome

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

logo

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


License

MIT License 2017 © Chad Donohue

You can’t perform that action at this time.