Notice: Maintainer wanted

I no longer have time to maintain this project in a timely manner and am looking for someone to take over. If you are interested please contact me.

# Readme Color.js provides an API to do simple color management in javascript. Color objects provide methods to do a number of common, useful operations independent of the underlying color model they need. The library supports RGB, HSV and HSL color models, along with alpha channel on all of them. CSS string representations of colors are supported for convenience. If you need colorspace management that correlates to human perception rather than display technology, [colorspace.js](http://boronine.com/colorspaces.js/) looks like an excellent library. Color objects are always immutable; all operations on them return new objects. This API is designed for correctness and clarity first, but operates at the expense of some performance. If you need raw performance look for a library that forces you to do the cloning and conversion yourself, rather than implicitly as this one does. > **Note:** In 2017 it's quite possible that you don't need this library, particularly for client side tasks; many use-cases can simply be achieved using CSS RGB, HSV, and HSL color syntaxes. # Using the library Once you have included the library in your page, you can access the public namespace `net.brehaut` (reverse DNS scheme). The only export from `color.js` is the `Color` factory function. You may wish to import this into your local scope, eg: var Color = net.brehaut.Color; You can use the library in a CommonJS environment, too: var Color = require('./color').Color; `Color` will create a new object for you from an object, string, or array. Note that this is a factory function, _not_ a constructor. eg: var Green = Color("#00FF00"); var Red = Color({hue: 0, saturation: 1, value: 1}); var Blue = Color("rgb(0,0,255)"); var Cyan = Color({hue: 180, saturation: 1, lightness: 0.5}); var Magenta = Color("hsl(300, 100%, 50%)"); var Yellow = Color([255,255,0]); Each method on a color either returns a new color (or set of colors) or returns a value. You can chain manipulation methods together as much as you need. Eg var C1 = Red.shiftHue(45).darkenByRatio(0.5).desaturateByAmount(0.1); A common use case for this code is to set page elements colors to calculated values, the method `toCSS` provides a string for you to use. eg: document.getElementById('myElement').style.backgroundColor = C1.toCSS(); # Methods There are three sorts of operations available on color objects; accessor methods (eg `getHue`/`setHue`), methods that manipulate the color and return a new object (eh `shiftHue`) or methods that return arrays of colors (eg, `splitComplementaryScheme`), and methods that do conversion and construction (eg `toCSS`). All values are a float from 0 to 1, with the exception of _hue_ which is a degree (from 0 to 360). ## Notes on terminology - A ratio multiplies the existing property by the ratio. - An amount is just added directly to the existing value. If you have a saturation of 0.7 and you apply a *ratio* of 0.5 the new color has a saturation of 0.35. If you then add an *amount* of 0.15 to that color’s saturation the final color will have a saturation of 0.5. ### Accessor Methods These methods are automatically generated by the API and are used to access the properties of the object. It is advisable to use these methods than try to access the property directly as the API makes no guarantees about the specific model members available. * `getRed()` : Number * `setRed( newRed )` : Color * `getGreen()`: Number * `setGreen( newGreen )` : Color * `getBlue()` : Number * `setBlue( newBlue )`: Color * `getHue()` : Number (degrees) * `setHue( newHue )` : color * `getSaturation()` : Number * `setSaturation( newSaturation )` : Color * `getValue()` : Number * `setValue( newValue )` : Color * `getLightness()` : Number * `setLightness( newValue )` : Color * `getLuminance()` : Number --- returns a number between 0 and 1 that represents how bright this color appears on a conventional monitor. * `getAlpha()` : Number * `setAlpha( newAlpha )` : Number ### Color Methods The following methods all return a new color. * `shiftHue( degrees )` : Color * `darkenByAmount( amount )` : Color * `darkenByRatio( ratio )` : Color * `lightenByAmount( amount )` : Color * `lightenByRatio( amount )` : Color * `devalueByAmount( amount )` : Color * `devalueByRatio( ratio )` : Color * `valueByAmount( amount )` : Color * `valueByRatio( amount )` : Color * `desaturateByAmount( amount )` : Color * `desaturateByRatio( ratio )` : Color * `saturateByAmount( amount )` : Color * `saturateByRatio( ratio )` : Color * `blend( color , alpha )` : Color --- returns a new color that is self blended with alpha of `color`. eg `black.blend ( white , 0 )` is black, `black.blend ( white , 0.5 )` is grey and `black.blend ( white , 1 )` is white. The following methods return a list of colors * `schemeFromDegrees( listOfdegrees )` : List of Colors * `complementaryScheme( )` : List of Colors * `splitComplementaryScheme( )` : List of Colors * `splitComplementaryCWScheme( )` : List of Colors * `splitComplementaryCCWScheme( )` : List of Colors * `triadicScheme( )` : List of Colors * `clashScheme( )` : List of Colors * `tetradicScheme( )` : List of Colors * `fourToneCWScheme( )` : List of Colors * `fourToneCCWScheme( )` : List of Colors * `fiveToneAScheme( )` : List of Colors * `fiveToneBScheme( )` : List of Colors * `fiveToneCScheme( )` : List of Colors * `fiveToneDScheme( )` : List of Colors * `fiveToneEScheme( )` : List of Colors * `sixToneCWScheme( )` : List of Colors * `sixToneCCWScheme( )` : List of Colors * `neutralScheme( )` : List of Colors * `analogousScheme( )` : List of Colors ### Conversion and Construction * `fromObject( o )` : Color --- `o` is an object with values from a color model, a css string, or an RGB array. * `toCSS([bytesPerChannel])` : String --- css hexdecimal representation. `bytesPerChannel` defaults to 2 * `toString()` : String --- returns CSS representation * `toHSV()` : Color * `toRGB()` : Color * `toHSL()` : Color ## Type definitions Users of [TypeScript](http://typescriptlang.org/) can find type definitions in `color.d.ts`. # Library design notes This library has been designed for correctness and with ease of use in mind. With regard to ease of use, `Color` objects allow you to chain operations by returning a new object each time. These operations involve common modification to the values in the object by a value or by a ratio where suitable, and automatically convert to the appropriate color model as required. The models chosen have been picked with regard to what makes most sense to a web developer, and ease of implementation, hence RGB, HSV and HSL. Internally theres a bit of metaprogramming soup to make it easier to define color models correctly, and ensure that colors remain values. # Demo * [Using color-js with Angular 2](https://plnkr.co:443/Y7scVM) # Changes

Jan 24, 2017

Version 1.0.4: Changed type declaration for using with Angular 2

May 12, 2015

Version 1.0.2: Add package.json for NPM publishing.

May 3, 2013

Version 1.0.1: Bug fix for alpha support in achromatic HSV to RGB.

May 1, 2013

Version 1.0

Alpha channels are supported on all color models.

April 16, 2013

Version 0.6

fromArray RGB factory added. This factory takes an array of three RGB values as ints from 0-255.

March 4, 2013

Version 0.5

Fixes bug where lightenBy…/darkenBy… used value property from HSV model, despite HSL now being supported.
valueBy…/devalueBy… methods added. These behave like the old lightenBy…/darkenBy… methods.
Module function now uses strict mode.

July 24, 2010

Version 0.4

Support for HSL color model
Common.JS module support
Minor bug fixes

January 14, 2008

Version 0.3 released

JSLint is now happy with it.
Approx 25% faster by caching factory constructor functions — effectively unrolls object

January 13, 2008

Version 0.2 released

Code tided up, now with comments
Docs written
Small edges cases implemented, eg, a black Color is returned if invalid arguments are passed
CSS named colors are supported

	Stars	Issues	Version	Updated	Created
color-js	829	3	1.0.5	5 years ago	9 years ago
colors	5,153	88	1.4.0	5 years ago	13 years ago
onecolor	532	7	4.1.0	5 months ago	12 years ago
parse-color			1.0.0	10 years ago	10 years ago
tinycolor2	4,946	100	1.6.0	a year ago	12 years ago

color-js vs colors vs onecolor vs parse-color vs tinycolor2

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past