and color variations. This includes parsing all standard CSS3 color formats such as
rgba(54, 128, 255, .8) and
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
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.
Please consider donating if you find the library useful and worth supporting. Or better...
...do you have a project that Pusher, Inc. could help develop?
We're a small, but talented team devoted to high-quality, challenging creative and technical work. Please consider us!
Licensed under the MIT license with a sincere request for donations based on your use.
The library has no dependencies; simply include the script file in your HTML page.-->
The library aims to conveniently support many different forms of color specification, so that it will work well within many host applications. See the full documentation for all support color and number formats.
To use a color value in an HTML page, simply specify the desired format:
The foremost goal of pusher.color is to be intuitive to use.
The basic usage should take only several minutes to learn and the rest of the functionality is intended to behave as the user would expect. Keeping the API simple and consistent is a primary goal.
Suggestions to simplify and improve the API or its documentation are always welcome.
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.
Enter a color in the input below or click on one of the generated color swatches to generate a new set of derived colors.
This example shows how to modify the color of each pixel in a given
element. It uses jQuery, underscore, and the HTML5 Canvas API to do the majority
of the work. The color modification is within the inner loop of the
pixel data modification.
The original image is given at the top. The image below is dynamically generated by the script.
A pusher Color object is created by calling the
pusher.color function with the
color to parse. In some cases, the function can determine the color format implicitly
but in others requires an explicit format argument to tell
how to parse the color data.
In the case of implicit formats,
pusher.color takes a single argument containing
a string representing the color. All standard
CSS3 color formats
are parsable as implicit color formats.
Explicit format parsing interprets the first argument as a the format to use and the following arguments represent the color description.
There are a wide variety of "fairly standard" color formats in use. Pusher.color.js generally assumes any CSS standard format in the case of ambiguity; however, by explicitly specifying the format, other formats can be used. It is never an error to explicitly specify the format to use.
See the CSS3 basic color keywords for an official reference of all supported colors.
See the CSS3 extended color keywords for an official reference of all supported colors.
The extended color formats are formats that are not part of the CSS3 specification.
The percent sign is optional on the saturation and value specification.
'rgba8' format is identical to the
with the exception that the alpha value (i.e. the fourth component) is specified in a 0-255 range
as opposed to as a 0.0-1.0 floating point value. The 'rgb8' format is also provided and is
completely identical to the 'rgb' format; it is provided simply for consistency.
rgba8 format interprets the alpha value as in the range of 0-255.
this is the format of the pixel data returned from a call to
getImageData() on an
'float4' formats are identical to the
with the exception that the color values (i.e. the first through third components) are specified in a 0.0-1.0 floating point range
as opposed to a 0-255 value.
both signed and unsigned integers are handled correctly by
red(), green(), blue()
Returns the red, green, or blue component of the color as a 0-255 value.
red(value), green(value), blue(value)
Sets the red, green, or blue component of the color. Expects a value in the range 0-255.
red('op value'), green('op value'), blue('op value')
Modifies the red, green, or blue components of the color.
Valid ops are
In the case of the operands with an
= the color is modified in place; otherwise, a copy of the color is made
and a new modified color is returned.
hue(), saturation(), value()
hue('op value'), saturation('op value'), value('op value')
hue('op', value), saturation('op', value), value('op', value)
alpha() method returns the alpha value of the color in the standard CSS3 0.0-1.0 range.
alpha8() method returns the alpha value in the 0-255 range (note: the "8" comes from the
'rgba8' format, where the 8 is the number of bits used per channel to store the color).
luminance() method returns the luminance of the RGB color based
on a biased weighting of 0.2126, 0.7152, 0.0722.
grayvalue() method returns the unweighted average of the RGB color.
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.
A shade is a color with black mixed into it.
Tone is a color with gray mixed into it.
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.
mul are also available.
These methods work just like
subtract() except that they modify the calling object.
Multiplies each color component by a uniform scale factor.
The scale factor does not apply to the alpha channel.
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.
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.
Returns the color opposite in hue on the color wheel. This is effectively equivalent to
The compliment of a color's complement is always the original color.
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') ].
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.
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.
For dark colors, returns white and for bright colors, returns black. This can be useful for choosing a background color for an arbitrary color.
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.
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.
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
'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.
Alpha values are not supported by this format and are implicitly dropped during the conversion.
These methods return the color as an array of 0-255 ranged color components.
rgba8() format is the format used internally for pixels in
CANVAS elements and can be useful for manipulating canvas
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.
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.
html(format)including format 'keyword'