New Color Picker in WP 3.5 

You may have noticed that WordPress 3.5 is sporting a new color picker. We originally developed it for the Custom Colors feature on WordPress.com. We offered it to WordPress Core, and 4 months, eleventy million tests and iterations later, there’s a shiny new, HiDPI-ready, CSS gradient-based color picker called Iris in your WordPress. But how do you use it?

The easiest way possible is in the Customizer. Keep registering your color controls the same way you always have and they’ll now sport a slick new Iris-based color picker interface. Otto’s great Theme Customizer tutorial shows you how to register controls, including a color control, so I won’t repeat that information here.

Want to use the new color picker somewhere else? Here’s a quick guide:

1. Enqueue the ‘wp-color-picker’ script and style

add_action( 'admin_enqueue_scripts', 'mw_enqueue_color_picker' );
function mw_enqueue_color_picker( $hook_suffix ) {
	// first check that $hook_suffix is appropriate for your admin page
	wp_enqueue_style( 'wp-color-picker' );
	wp_enqueue_script( 'my-script-handle', plugins_url('my-script.js', __FILE__ ), array( 'wp-color-picker' ), false, true );
}

My plugin now has a my-script.js file that has declared wp-color-picker as a dependency. We can now use the wpColorPicker jQuery method inside it.

2. Add an input to your admin page

I’m not going to tell you how to code an admin page. Somewhere on it, you’ll want:

<input type="text" value="#bada55" class="my-color-field" />

You can also prime a default color for the field if you want:

<input type="text" value="#bada55" class="my-color-field" data-default-color="#effeff" />

3. Call ‘wpColorPicker’ from your script

Remember that we enqueued my-script.js above? Open it up, and be prepared for some long coding:

jQuery(document).ready(function($){
	$('.my-color-field').wpColorPicker();
});

What, you wanted more? There’s a lot more you can do, but that will get the job done for most cases. (Note that only IE8 and up are supported. IE7 and under will fail gracefully, leaving you with a perfectly usable text input.)

4. Advanced usage

wpColorPicker supports a few options. You can supply an options object when calling it:

var myOptions = {
	// you can declare a default color here,
	// or in the data-default-color attribute on the input
	defaultColor: false,
	// a callback to fire whenever the color changes to a valid color
	change: function(event, ui){},
	// a callback to fire when the input is emptied or an invalid color
	clear: function() {},
	// hide the color picker controls on load
	hide: true,
	// show a group of common colors beneath the square
	// or, supply an array of colors to customize further
	palettes: true
};

$('.my-color-field').wpColorPicker(myOptions);

5. More advanced usage

wpColorPicker is set of UI controls wrapped around the underlying Iris color picker. We did things this way so that, if a better color picker comes along, we can more easily swap it out. But, if you want to just play with Iris itself, just declare iris as your script dependency instead. I’m not going to document the options here, but Iris’s GitHub repo should see some actual docs in the future.