A(n awesome) Color Picker.
Iris uses CSS3 Gradients for everything, so it’ll look awesome on HiDPI displays out of the box. Initially developed for Custom Colors on WordPress.com and shipping with WordPress 3.5+.
Iris relies on jQuery 1.7 and up, and the draggable and slider jQuery UI components. (Those then presume jQuery UI core, widget, and mouse components. Just use the jQuery UI download builder and it’ll sort out your dependencies)
Just use the latest version of both jQuery and jQuery UI and you’ll be golden.
Download the zip on the the repo or clone it or pull it or whatever you’re most comfortable with. There are minified or full versions in the dist directory. The -basic versions do not bundle the Color.js dependency, which you would then have to include separately.
Then do something like the following:
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.9.2/jquery-ui.min.js"></script>
<script src="path/to/iris.min.js"></script>
<script src="path/to/my/javascript.js"></script>
Note that the above example is just an example. Use your discretion. You may not need all of jQuery UI, for instance, and you probably want some kind of system for concatenating/managing your scripts.
Iris is easy to use, just assign it to an input element. Say you have:
<input type="text" id='color-picker' value="#bada55" />
Now, assuming you have a JavaScript file like path/to/my/javascript.js above, just write the following:
jQuery(document).ready(function($){
$('#color-picker').iris();
});
And now you’ll have a color picker on that element. Well, by default, it’ll only show once you click/focus on the input element. Like below:
Defaults are powerful, but they may also be wrong for the situation you want to use Iris in. Iris takes an options object when you call it. Like maybe a wider, show-by-default picker:
jQuery(document).ready(function($){
$('#wide-load').iris({
width: 400,
hide: false
});
});
Produces:
Okay, enough with the chit-chat. Here’s the list of default option keys followed by more details of what they do:
options = {
color: false,
mode: 'hsl',
controls: {
horiz: 's', // horizontal defaults to saturation
vert: 'l', // vertical defaults to lightness
strip: 'h' // right strip defaults to hue
},
hide: true, // hide the color picker by default
border: true, // draw a border around the collection of UI elements
target: false, // a DOM element / jQuery selector that the element will be appended within. Only used when called on an input.
width: 200, // the width of the collection of UI elements
palettes: false // show a palette of basic colors beneath the square.
}
If Iris is attached to an input element, it will first try to pick up its value attribute. Otherwise, you can supply a color of any type that Color.js supports. (Hex, rgb, and hsl are good bets.)
Iris can sport a variety of looks. It supports hsl and ‘hsv’ modes depending on your needs.
Iris is flexible like a gymnast. You can change all 3 directions of it controls. Just make sure you cover all 3 aspects of hsl or hsv that you chose in the mode option. horiz and ‘vert’ sets the horizontal and vertical aspects of the square, respectively, while the strip options sets the rightmost strip.
Iris hides until you call on it by default. Set to false to show right away.
Set to true to display a border around the square and strip controls.
If you are attaching Iris to an input element, you may wish to display it somewhere other than directly after the element you are calling it on. Supply a DOM element or a jQuery selector. This will be ignored when not called on an input element.
The width, in pixels, that the combined interface should take up. Because Iris is drawn with CSS gradients, you can make it any size.
Set to true to display a row of common palette colors. This is particularly useful in situations where the currently selected color seems to make no colors available. Example:
$('#palette-example').iris({
hide: false,
palettes: true
});
Or, you can supply an array of colors to use your own palette colors.
$('#palette-example2').iris({
hide: false,
palettes: ['#125', '#459', '#78b', '#ab0', '#de3', '#f0f']
});
Supply a change function when calling Iris to do stuff when the color changes. In the example below, the headline will change colors when you modify Iris.
$('#change-example').iris({
hide: false,
change: function(event, ui) {
// event = standard jQuery event, produced by whichever control was changed.
// ui = standard jQuery UI object, with a color member containing a Color.js object
// change the headline color
$("#headlinethatchanges").css( 'color', ui.color.toString());
}
});
See Color.js documentation for what you can do with that ui.color object. In most cases, you’ll just want ui.color.toString() to produce a hex color string.
Iris supports a couple of methods out of the box.
Like most jQuery UI-based widgets, you can get/set all of the options intitially passed to Iris. The controls option, as noted above, might be a bit squirrely.
$(element).iris('option', 'width'); // retrieve the current width
$(element).iris('option', 'width', 500); // set the width to 500px. Because reasons.
A get/set method for Iris’s color, with a twist: call true in the second argument to return the associated Color.js object.
$(element).iris('color'); // retrieve the current color
$(element).iris('color', true); // retrieve the Color.js object
$(element).iris('color', '#bada55'); // set the color to #bada55
Reveal a hidden Iris color picker
$(element).iris('show');
Hide a visible Iris color picker
$(element).iris('hide');
Toggle the visibility of an Iris color picker
$(element).iris('toggle');