jQuery Colors Plugins

jQuery.colors helps developers manage colors through a simple, chainable color object.
It has a modular design allowing you to get rid of what you don't need or extend it for your custom ideas (and hopefully, for everyone's benefit).

Example usage

$.colors( [255,0,0] ).toString('hex');
$.colors( [1,0,0], 'array3Normalized' ).format('array3Octet');
$.colors( 'lightCoral' ).model('HSL').get();
$.colors( 'hsla(0,100%,50%,0.4)' ).toString('name');
var mix = $.colors( 'Orange' ).mixWith( [ [128,255,0], '#f00' ] );
mix.get('red');
// fades to and back from transparent
// (mimics the parent's background if no rgba support - can be auto detected but this is disabled for the examples)
$('#demoBlock').animate({backgroundColor:'transparent'},2000,function(){
  $(this).text( $(this).css('background-color') );
}).delay(250).animate({backgroundColor:'#f00'},2000);
// first a direct fade, then back to same color but cycling through the rainbow
$('#demoBlock').animate({backgroundColor:'rgb(0,128,0)'},4000)
  .animate({backgroundColor:'red'},{duration:4000,mixModel:'HSL'});

Why another color plugin?

Basically, there are a few color plugins out there with lots of clever functions but no external access to them.
This plugin (well, family of plugins) tries to simplify future development of color manipulating plugins for everybody using jQuery.

Download from Github (requires jQuery 1.3.2+
-earlier versions may work too!)

Files and features

jQuery.colors.core.js

  • Required
  • Provides ability to create the $.colors() with key functions and sets default settings
  • Adds the model: 'RGB'.
  • Adds the formats: 'rgb', 'array3Octet' and 'array3Octet1Normalized'

jQuery.colors.mix.js

  • Adds the function .mixWith() to the $.colors object

jQuery.colors.animate.js

  • Requires jQuery.colors.mix.js
  • Extends jQuery's default animate function to include colors. Essentially like jQuery.color.js (used in jQuery UI) but more versatile and without unecessary bloat.
  • Also adds a new function .visibleColor() to the jQuery object.

jQuery.colors.browserSupport.js

  • Detects and extends jQuery.support for rgba, hsl and hsla Strings
  • If rgba is supported, the $.colors.defaultString is automatically changed to rgba

jquery.colors.models.HSL.js

  • Adds the model: 'HSL' (hue, saturation, lightness)
  • Adds the formats: 'array1Circle2Percentage' and 'array1Circle2Percentage1Normalized'

jQuery.colors.formats.[...].js

  • These files add many formats:
    • 'rgba'
    • 'hex'
    • 'transparent'
    • 'array3Normalized' and 'array4Normalized', plus extensions for HSL
    • 'name' (containing the common X11 HTML names)
    • 'hsl' and 'hsla'

Documentation (with demos)

$.colors()

Creates a randomly generated color. Returns the color object.

$.colors( colorInput, [formatName], [modelName] )

Creates a color based on the arguments. Returns the color object.

colorInput A string or array representing a color

formatName The name of the format of the color

modelName The name of the color model of the color

If no color format is given, it will be guessed from the known existing formats.
A format may map to several color models, so the assumed model is the one set (in order of priority) by the argument in this function, or by the format itself, or finally as given by $.colors.defaultInputModel
If the color model of the input color is not the same as $.colors.defaultModel, it will be transformed to the default model.

$.colors().toString('hex'); // random
$.colors( [0.5,0.5,0.5,0.9] ).get();
 // Not the 'array3Octet' format (both match the input) ( array1Circle2Percentage is for HSL )
$.colors( [128,0,0], 'array1Circle2Percentage' ).toString();
$.colors( [0,1,0.5], 'array3Normalized', 'HSL' ).toString('hsl');
// Note: correctly interprets input as HSL but the default model is still RGB so an RGB array is returned
$.colors( [0,1,0.5], 'array3Normalized', 'HSL' ).get();

A note on alpha support

Alpha support is built-in. For the RGB and HSL models, an additional parameter is appended with the alpha value (between 0 and 1). If not specified by a color input, it will default to 1. 'transparent' creates a white color with value of 0 for alpha, except during animations (see below).
For the purposes of these demonstrations, auto detection of alpha support has been removed, so that you can see fallback solutions.


aColorObject.get( [parameter] )

Returns the color as an array, or just the single parameter as a number (if specified).

parameter A name for the parameter to get (e.g. 'r', or 'Green')

$.colors( [255,128,0] ).get();
$.colors( [255,128,0] ).get('Green');

aColorObject.set( parameter, value )

Sets the parameter to the value. Returns the color object.

parameter A name for the parameter to set (e.g. 'h', or 'Alpha')

value The number to which to set the parameter

$.colors( [255,128,0] ).set('Blue',128).toString();

aColorObject.format( formatName )

Returns the color in the given format (an array or a String).

formatName The name of the format to return

$.colors( [255,128,0] ).format('array3Normalized');

aColorObject.toString( [formatName] )

Returns a String value of the color in the given format.

formatName The name of the format to return

Similar to aColorObject.format() except that it will always return a String, and formatName is optional: if no format is specified it will use format given by $.colors.defaultString (initially 'rgb').

$.colors( [0,255,0,0.7] ).toString('hsla');

aColorObject.isFormat( formatName )

Returns true if the original input of the color object is a valid form of the given format name.

formatName The name of the format to validate against

// both of these examples are true, so there may be confusion
$.colors( [255,63,63] ).isFormat('array3Octet');
// to avoid any misinterpretations on the input, specify the format name
$.colors( [255,63,63] ).isFormat('array1Circle2Percentage');

aColorObject.mixWith( color, [baseDosage] )

Blends the color object (base color) with one or several colors. Returns a new color object.

color Either a color object, or a new color input, or an array of either of these options (or a mix of both).

baseDosage A number between 0 and 1 giving the weight of the base color compared to the other colors.

The color used to call this function is referred to as the base color.
Typically mixing implies averaging each individual parameter of their color value (including alpha). If a base dosage is given, this average is weighted accordingly. If multiple colors are given to mix with, this weighting applies to the base and the average of all the other colors.
The mixing is done according to the base's color model (other's will be converted). The difference in results is clear, especially when animating colors (see below).
Note: the original colors are not affected (a new color object is created), hence the name 'mixWith' instead of 'blend' or something..

$.colors( [255,0,0] ).mixWith( [0,0,255] ).toString();
// remember, the original color objects are not changed
var mix = $.colors( [255,0,0] );
$('#demoBlock').text( mix.mixWith( [ 0,0,255 ] ).toString() );
mix.toString();
$.colors( [0,0,255] ).mixWith( [ 'rgb(255,0,0)', $.colors( 'rgb(0,255,0)' ) ] ).toString();
$.colors( [0,0,0] ).mixWith( [ [0,0,255], 'rgb(255,0,0)', $.colors( 'rgb(0,255,0)' ) ] ).toString();
$.colors( [255,0,0] ).mixWith( $.colors( [0,0,255] ), 0.75 ).toString();

jQueryObject.visibleColor( colorPropertyName )

Returns the property of the element if set, if not it returns the color of the first ancestor to have a background that is not transparent.

colorPropertyName The property name of a CSS style that returns a color.

The returned value is essentially the color of the property as currently visible to the user. Used for animations (below) and possibly useful elsewhere.

$('#demoBlock').visibleColor('color');

jQueryObject.animate()

Extends jQuery's animate function by adding background, borders and text colors to the 'properties' argument.

Any String format used by the $.colors object will be recognized, for example, this includes rgba formats. Animating to or from 'transparent' will mimic the background's color temporarily during the animation.
Additionally, if you'd like to animate in a color model other than the default $.colors.defaultModel you can set the mixing color model per animation by naming it in the 'options' object, with the property name mixModel:
Currently only for hue in the HSL model, some color models have cyclical parameters. The direction of the cycle can be reversed with the command : $.colors.models.HSL.reverseCylce('hue');. In this case, the colors of the rainbow would originally go from red to blue, but could then go back from blue to red.

$('#demoBlock').animate({backgroundColor:'#0f0'},2000)
  .animate({backgroundColor:'red'},2000);

Animating alpha

Remember, auto detection (from jQuery.colors.browserSupport) has been disabled for the demos!

// fades to transparent and back to default CSS (with blank CSS property)
$('#demoBlock').animate({backgroundColor:'transparent'},2000,function(){
  $(this).text( $(this).css('background-color') );
}).delay(500).animate({backgroundColor:''},2000);
// this time we set the defaultString to 'rgba' (only different if your browser supports rgba)
$.colors.defaultString = 'rgba';
$('#demoBlock').animate({backgroundColor:'transparent'},2000,function(){
  $(this).text( $(this).css('background-color') );
}).delay(250).animate({backgroundColor:''},2000,reset);
// uses rgba as an input, but as defaultString equals 'rgb', so we don't notice the alpha
$('#demoBlock').animate({backgroundColor:'rgba(0,128,0,0.3)'},2000,reset);
// again, we set defaultString to 'rgba' (only different if your broswer supports rgba)
$.colors.defaultString = 'rgba';
$('#demoBlock').animate({backgroundColor:'rgba(0,128,0,0.3)'},2000,reset);
// we could fake alpha support by mixing the desired color with the backgroud
var parentsColor = $('#demoBlock').parent().visibleColor('background-color');
var color = $.colors( 'rgba(0,128,0,0.3)' );
var fakeAlphaColor = color.mixWith( parentsColor, color.get('alpha') );
$('#demoBlock').animate({backgroundColor:fakeAlphaColor.toString()},2000,reset);

Animating with HSL

// first a direct fade in RGB (default), then back to same color with HSL
$('#demoBlock').animate({backgroundColor:'rgb(0,128,0)'},4000)
  .animate({backgroundColor:'red'},{duration:4000,mixModel:'HSL',complete:reset});
// we can make everything go through rainbows by changing the default color model
$.colors.defaultModel = 'HSL'
$('#demoBlock').animate({backgroundColor:'rgb(255,0,1)'},4000,reset);
// as it's a cycle, we can go both ways...
$.colors.defaultModel = 'HSL';
$.colors.models.HSL.reverseCylce('hue');
$('#demoBlock').animate({backgroundColor:'rgb(255,1,0)'},4000,reset);

◂ Back to the code section