colorjoe - The Scaleable Color Picker

colorjoe was somewhat inspired by ColorJack and RightJS Colorpicker. Unlike those it actually scales pretty well. Essentially this means that you'll be able to define its actual dimensions and layout using a bit of CSS. This way the widget fits well responsive layouts.

In addition it's relatively easy to implement missing functionality (RGB fields, whatnot) thanks to the simple API it provides.

Installation

Add prepackaged dist/colorjoe.js and css/colorjoe.css to your page or use AMD to load the dependencies from src/.

Note that you need to load one.color before using colorjoe. In case you are using RequireJS, shim it at your configuration so that it is bound to onecolor.

Usage

var joe = colorjoe.rgb(element_id_or_dom_object, initial_color_value, extras);

var joe = colorjoe.hsl(element_id_or_dom_object, initial_color_value, extras);

Event Handling

The returned joe object is an event emitter style object with change and done events. The change event is fired continuously when selecting and done is fired when user has stopped selecting.

joe.on("change", function(color) {
    console.log("Selecting " + color.css());
});

joe.on("done", function(color) {
    console.log("Selected " + color.css());
});

The color object is from one.color.

Given it might be nice to trigger these events immediately, there is a specific update method. Ie. joe.on("change", function() {...}).update() would trigger change immediately. This is handy for initializing your work.

Get and Set

In addition there are set and get methods. Ie. joe.get() would return the current color while joe.set('#aabbcc') would set it. set expects a parameter that one.color default constructor would accept.

Extras

In order to make it easier to customize a picker based on your needs, colorjoe provides a few extras. The following example shows how to use them:

var joe = colorjoe.hsl('hslPicker', 'red', [
    'currentColor',
    'alpha',
    ['fields', {space: 'HSL', limit: 255, fix: 0},
    'hex'
]);

The code above would generate a HSL picker that shows in addition the currently selected color, alpha slider, HSL input fields and a hex field.

As you can see fields has been defined using an array. This array contains the name of the extra and then parameters passed to inside an object. In this case the extra accepts name of a color space (RGB, HSL, HSV or CMYK). If you append A to the color space, it will show a control for alpha too. In addition it takes a limit value (defaults to 255) and a fix value (defaults to 0). fix represents the amount of numbers shown after decimal.

hex extra accepts optional label. If set it will show that as the input's label.

Implementing Custom Extras

It is possible to implement your custom extras without having to hack the core code. This can be done as follows:

colorjoe.registerExtra('text', function(p, joe, o) {
    // attach new elements to p element here (as children that is)
    // o is optional and will contain any parameters you might have
    // passed to the extra using the array syntax

    // optional return. these are triggered by colorjoe
    // use this way instead of joe.on
    return {
        change: function(col) {},
        done: function(col) {}
    };
})

Now you can simply pass your text extra amongst the others and it will just work.

Sites Using colorjoe

PRs are welcome!

Contributors

Juho Vepsäläinen - Core
Esa-Matti Suuronen - Grunt support + removeAllListeners
Peter Müller - one.color + HTML tweaks
Edmundas Kondrašovas - Callback done fix
Fabio Caseri - Use hex code instead of black
Artem Zakharchenko - Fix issue with initial color when it was set black on RGB (#20).
Tyler Waters - Improve CSS to work with IE better. Ensure done callback is fired for extras. Add validation to extra fields to avoid exceptions from one-color.
Elsa Balderrama - Trigger done correctly for alpha slider.
Jesse Keane - Add onecolor to package.json so that colorjoe works with Browserify
Sam Potts - Improve formatting, generate random ids for labels, IE9+ support.