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 An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. We offered it to WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., and 4 months, eleventy million tests and iterations later, there’s a shiny new, HiDPI-ready, CSSCSS Cascading Style Sheets. gradient-based color picker called Iris in your WordPress. But how do you use it?

The easiest way possible is in the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.. 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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party 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 adminadmin (and super 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:


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


5. More advanced usage

wpColorPicker is set of UIUI User interface 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.

#3-5, #dev-notes