pusher.color.js
A flexible, intuitive Javascript color manipulation library

The pusher.color.js library is a Javascript library for parsing, manipulating, and formatting colors and color variations. This includes parsing all standard CSS3 color formats such as rgba(54, 128, 255, .8) and "Blue", parsing common non-web color formats such as HSV, converting betweeen formats, generating complementary colors, generating alternate tones and shades, and other generally useful functionality in dynamic, graphics intensive Javascript applications.

The library design is modelled after the excellent moment.js Javascript library for parsing, manipulating, and formatting dates.

—

Note: The library uses a semantic versioning scheme and is still considered an in-development API. Please feel free to use the library and report suggestions, errors, or questions; however, at this early stage of development full support and backwards compatibility can not be guaranteed.

Download v0.2.4

Manipulation

The library supports many operations for manipulating a given color. Change the color saturation, reduce the amount of green, blend with another color, find the color's complement, find a different tone of the same base color, etc.

tint(amount)

A tint is a color with white mixed into it.

Amounts may be specified as a floating point value, a parseable floating-point string, or as percentages.

shade(amount)

A shade is a color with black mixed into it.

tone(amount)

Tone is a color with gray mixed into it.

blend(color, amount)

The blend operation linearly mixes two colors by their RGBA component values. An input of 0 will result in an unmodified copy of the first color whereas an input of 1 will result in a unmodified copy of the second color.

In keeping with much of the API, the blend can be specified as a percentage as well. Also note the first color argument will be parsed as a color object if it is not already one.

add(), subtract(), multiply()

Component-wise operations on the colors. The operations use a floating point color component representation that, for example, would mean a red multipied by a grey becomes darker, not brighter.

inc(), dec()

scale(factor)

Multiplies each color component by a uniform scale factor.

The scale factor does not apply to the alpha channel.

xor(color)

Treats the two colors as bitfields and applies an XOR operation to the red, green, and blue components.

Note: the XOR is not applied to the alpha component and the source color's alpha is copied directly to the resulting color.

clamp()

Clamps the internal representation of the color to a displayable range. This method is not often necessary to call explicitly, but may be desired as an intermediate operation when values are known to exceed displayable range and the excess range is not desired for subsequent operations.

complement()

Returns the color opposite in hue on the color wheel. This is effectively equivalent to color.hue('+180').

The compliment of a color's complement is always the original color.

triad()

Returns a set of three colors including the color itself and the two colors to 120 degrees to the left and right of it on the color wheel. Effectively equivalent to [ color, color.hue('-120'), color.hue('+120') ].

hueSet()

Returns a set of nine colors of varying saturation and value all with the source color's hue. Useful for generating a set of distinguishable, but similar colors.

hueRange(range, count)

Returns a set of count colors evenly spaced along a range in hue. The range determines how many degrees to vary from the hue in both directions, resulting in a total span of 2 * range.

contrastWhiteBlack()

For dark colors, returns white and for bright colors, returns black. This can be useful for choosing a background color for an arbitrary color.

contrastGray()

Returns a grayscale equivalent of the color that differs in value by 30% in order to make it clearly distinguishable from the source color. This can be useful for border colors or other subtly different contrast colors.

HTML Format

html()

Converts the color to a string format parsable by a CSS3-compliant web browser.

Note: the implementation does not guarentee which format will be used for output by html(). If a specific format is required, use an explicit call for that particular format.

html(format)

Converts the color to a string format parsable by a CSS3-compliant web browser. Note that only CSS3 format types as available (e.g. html('hsv') is not a supported format type). The resulting color is always the nearest match in case of inexact matches and the alpha value is dropped from formats not supporting alpha.

html('keyword')

The 'keyword' will find the nearest match for the color in RGB space. This is implemented with as an O(N) algorithm; and thus is not very efficient.

Hexidecimal Format

hex3(), hex6()

Alpha values are not supported by this format and are implicitly dropped during the conversion.

RGBA8 Format

rgb8(), rgba8()

These methods return the color as an array of 0-255 ranged color components. The rgba8() format is the format used internally for pixels in CANVAS elements and can be useful for manipulating canvas pixel colors.

FLOAT3, FLOAT4 Formats

float3(), float4()

Packed Formats

packed_rgba(), packed_argb()

These methods return the color as a single packed, unsigned integer. (The demo below displays the results as a hexidecimal string as well simply for the convenience of the reader.)

The pusher.color.js library is released under the MIT License

The license is an extremely lenient license. Please feel free to use the library in any manner you wish that is in conformance with the license. Contributions in the form of defect fixes, new features, code improvements, feedback & suggestions, and donations are always welcome but never required.

Please contact us at any time.

Special thanks to moment.js for the inspiration for a clean, well-documented API.

Thanks to...

• Asbjørn Andersen for adding bower compatibility. (And for nudging me towards making the library easier for others to contribute to!)
• Caolan McMahon for nodeunit, the simple get-out-of-the-way-and-do-what-its-intended-to-do node-based unit test module.
• Matt Haynes for the original HSV/RGB code.
• Michael Jackson for the HSL conversion code.

Acknowledgement as goes to the W3C for making public standards of the various color specifications this library uses. Openly available standards and specifications are good things.

The technology used to create and/or influenced the creation of the library and this web page includes jQuery, underscore.js, Twitter Bootstrap, google-code-prettify, Twig and many others. All of the aforementioned are recommended as useful tools.