jsColors
A JavScript color manipulation library

jsColors is a Javascript color-manipulation library. It goes beyond the usual manipulation of red, green and blue color channels and lets you easily set and get hue, value, and saturation, and create new colors by manipulating and tweaking existing colors.

API

Object

Color

The Color object is the only object in the jsColors library. Everything else is a method or property of the Color object.

To create a new instance of the Color object, just call the global Color() function with an optional argument. For example:

  • var myColor = Color() creates a default (black) Color object.
  • var myColor = Color("rgb(13, 176, 200)") creates a bright aquamarine.
  • var myColor = Color("#73E190") creates a minty green color.
  • var myColor = Color({red: 240, green: 120, blue: 115}) creates a rosy pink.

The great thing about the last technique is that the Color object itself has red, green and blue members, so you can write something like this:

var myNewColor = Color(myColor); // Create a copy of myColor

When used in a string context, the Color object automatically converts to an RGB color string, allowing constructs like this:

document.body.style.backgroundColor = myColor;

(NOTE: This does not work in Internet Explorer, due to IE’s failure to convert the Color object to a string when it should. Use the rgb() method instead.)

Properties

The Color object has three properties, red, green and blue, that can be read and set directly. They each take an integer value between 0 and 255, inclusive. If you try to set one of them to an out-of-range or non-integer value, it will get set to a valid value when you try to do anything with the Color object.

Methods

getHue()

Gets a value between 0 and 360, inclusive. The value represents a position, in degrees, around the color wheel. Red is at 0, green is at 120, and blue is at 240.

setHue(h)

Sets the Color’s hue. This method takes a number between 0 and 360, inclusive. Out-of-range and non-numeric arguments have no effect.

getSaturation()

Gets a value between 0 and 100, inclusive, representing the ‘brightness’ of the color. 100 is the brightest, and 0 is the dullest (i.e., gray).

setSaturation(s)

Sets the Color’s saturation. This method takes a number between 0 and 100, inclusive. Out-of-range and non-numeric arguments have no effect.

getValue()

Gets a value between 0 and 100, inclusive, representing the amount of black in the color. 0 is the darkest (i.e., pure black), and 100 has the least black.

setValue(v)

Sets the Color’s value. This method takes a number between 0 and 100, inclusive. Out-of-range and non-numeric arguments have no effect.

rgb()

Returns an RGB triplet string that can be assigned to CSS properties.

getComplement()

Creates a new Color object whose hue is on the opposite side of the color wheel from that of the original Color.

Example

#ex1
#ex2

Let’s begin by setting the background color for #ex1:

var ex1 = document.getElementById("ex1");

var c = Color("#dda0dd"); // plum

ex1.style.backgroundColor = c.rgb();

Now we’ll make it a bit brighter:

ex1.style.backgroundColor = Color(ex1.style.backgroundColor).setSaturation(60).rgb();

Make it a little less red:

var c = Color(ex1.style.backgroundColor);

c.red = c.red - 50;


ex1.style.backgroundColor = c.rgb();

Let’s set #ex2’s background color to #ex1’s complement:

var ex2 = document.getElementById("ex2");

ex2.style.backgroundColor = Color(ex1.style.backgroundColor).getComplement().rgb();

Finally, we’ll fade #ex2 to black:

(function fade() {

  var c = Color(ex2.style.backgroundColor);

  var v = c.getValue();

  if (v == 0) {

    return;


  } else {

    ex2.style.backgroundColor = c.setValue(v - 1).rgb();

    setTimeout(fade, 100);

  }

})();