A Colour Picker Widget For JavaScript

The colour picker (or colour chooser) is common widget, but its complexity has lead to a lack of JavaScript implementations. This article describes ColourPicker, an easy-to-use colour picker widget. An example of the widget is shown below.

Using ColourPicker

Download one of the JavaScript files listed above and upload it to your website. As indicated by the comment at the top of each file, the code is released into the public domain and is free to use for any purpose. ColourPicker also requires Colour, a collection of JavaScript functions that handle colour conversion. Link to them from your page with code such as:

<script type="text/javascript" src="Colour.js"></script>
<script type="text/javascript" src="ColourPicker.js"></script>

ColourPicker also requires a set of six small images (totalling 1273 bytes), available in one of the three archive formats listed above. Download one of these archives, extract the images, and then upload them to a directory on your website — usually the same directory as the script files.

Using ColourPicker

To create a colour picker, you first need to create a node in your document to contain it. This will usually be an empty div element, although it can contain content — the colour picker will be added after the content. For example:

<div id="colourPicker"></div>

The colour picker is then created by creating a new instance of ColourPicker referring to that node. The node must already exist at the time the ColourPicker instance is created. This can be done either by including the JavaScript code below the node in the document source code, or by calling the constructor only once the document has loaded — one way to do this is by using the OnloadScheduler.

The constructor should be called with two or three parameters:

node

the DOM node into which to insert the colour picker — the colour picker will be appended to this node as a child

imageDirectory

the path to the images used by the ColourPicker — this may be an absolute path or a path relative to the page, and should be the empty string if the images reside in the same directory as the page itself

defaultColour

a Colour object representing the default colour to display — this paramater is optional and defaults to black

For example:

// create a colour picker for the node with the id 'colourPicker'
var colourPicker1 =
    new ColourPicker(
        document.getElementById('colourPicker'),
        '');

// create a colour picker where the images reside in the 'images' directory
var colourPicker2 =
    new ColourPicker(
        document.getElementById('colourPicker'),
        'images/');

// create a colour picker with bright purple as its default colour
var colourPicker3 =
    new ColourPicker(
        document.getElementById('colourPicker'),
        '',
        new RGBColour(255, 0, 255));

ColourPicker

ColourPicker includes function to get and set the colour shown in the colour picker, and to add change listener functions (functions called when the colour changes). The functions are:

getColour

Returns the current colour in the colour picker as a Colour object. This will be an instance of RGBColour, HSVColour, or HSLColour.

setColour

Sets the current colour in the colour picker. The parameter is:

newColour

the new colour, as a Colour object

addChangeListener

Adds a new change listener. When the current colour in the colour picker changes, the each listener is called. Each listener is passed two parameters — the first is the current colour, and the second is the ColourPicker itself. The parameter is:

listener

the listener function to add

removeChangeListener

Removes the specified change listener. The parameter is:

listener

the listener function to remove