Upgrading to the New WordPress Color Picker

Key Takeaways

• Upgrading your WordPress plugin to the new color picker is simple, but the challenge comes in providing a fallback to the old Farbtastic color picker for older versions of WordPress. This can be achieved by checking the installed WordPress version and enqueuing the appropriate styles and scripts.
• The new WordPress color picker offers a user-friendly interface, a wider range of colors, consistency with the WordPress admin color scheme, transparency support, and an intuitive design. It is also mobile-friendly and compatible with all WordPress themes and Gutenberg blocks.
• If you’re starting to create plugins for WordPress, understanding how to create settings pages and call your styles and scripts within those pages is vital. This process involves using PHP to call your styles and scripts and JavaScript to initialize a color picker.

If you’re like me and you’ve been using the old Farbtastic color picker for a WordPress plugin, I’m sure you were eager to use the new and improved color picker with the release of WordPress 3.5. Upgrading your plugin to use the new color picker is fairly straightforward. What’s difficult is knowing how to easily fall back to the Farbtastic color picker for older versions of WordPress. In the following screencast and article we’ll talk through how to do exactly that and provide a full plugin example on Github to help get you started.

The Screencast

The Steps to Implement the WP Color Picker

Before getting to the nitty gritty PHP and JavaScript, let’s take a look at the steps to implement the new color picker.

1. Determine the version of WordPress installed on the server.
2. Enqueue both the styles and script for the new color picker if the install of WordPress is version 3.5 or higher.
3. If the WordPress version is less than 3.5, enqueue the styles and scripts for the deprecated Farbtastic color picker.
4. In your custom JavaScript file, check to see if the new color picker function exists and, if so, initialize the color picker on your text input field.
5. If the new color picker doesn’t exist, then initialize the Farbtastic color picker.

Pretty easy right? Now let’s take a look at the PHP we use within our plugin.

Use PHP to Enqueue the Right Styles and Scripts

If you’re just starting to create plugins for WordPress, you’ll need a solid understanding of how to create settings pages and how to appropriately call your styles and scripts within those pages. Going through how to create a settings page for your plugin isn’t in the scope of this article, but if you need more info on how to handle settings for your plugin, check out Creating Custom Options Pages in WordPress by Jeffrey Way. For our purposes, you’ll need to know that the final input field and necessary div on our admin page look like this:

<input id="color" name="color_options[color]" type="text" value="" />
<div id="colorpicker"></div>

view raw gistfile1.html Once you hook your function or method appropriately through add_action(), you’ll use PHP to call your styles and scripts:

< ?php
function add_styles_scripts(){
    //Access the global $wp_version variable to see which version of WordPress is installed.
    global $wp_version;
 
    //If the WordPress version is greater than or equal to 3.5, then load the new WordPress color picker.

    if ( 3.5 <= $wp_version ){ //Both the necessary css and javascript have been registered already by WordPress, so all we have to do is load them with their handle. wp_enqueue_style( 'wp-color-picker' ); wp_enqueue_script( 'wp-color-picker' ); } //If the WordPress version is less than 3.5 load the older farbtasic color picker. else { //As with wp-color-picker the necessary css and javascript have been registered already by WordPress, so all we have to do is load them with their handle. wp_enqueue_style( 'farbtastic' ); wp_enqueue_script( 'farbtastic' ); } //Load our custom javascript file wp_enqueue_script( 'wp-color-picker-settings', plugin_dir_url( __FILE__ ) . 'js/settings.js' ); } ?>

view raw gistfile1.php At the top of the method we use the global $wp_version variable which provides us with the version number for this install of WordPress. We simply check whether we’re using 3.5 or higher and if so, load the new color picker using the preregistered styles and script. Otherwise, we load the older Farbtastic styles and script. At this point we’ve loaded the correct files, but we need to call the script on our text input field. We do that through our own JavaScript file.

Use JavaScript to Initialize a Color Picker

You can see at the bottom of the add_styles_scripts() method above that we load one JavaScript file. In the short term, the easier way would be to have two Javascript files, one for the new color picker and one for Farbtastic. With this plugin that would be fine, but it would become very inefficient to manage if we had to update two files every time we needed to make a change to our JavaScript. So, how do we set up only one JavaScript file to initialize the right color picker?

//Set up the color pickers to work with our text input field

jQuery( document ).ready(function(){

    "use strict";
 
    //This if statement checks if the color picker widget exists within jQuery UI

    //If it does exist then we initialize the WordPress color picker on our text input field

    if( typeof jQuery.wp === 'object' && typeof jQuery.wp.wpColorPicker === 'function' ){

        jQuery( '#color' ).wpColorPicker();

    }

    else {

        //We use farbtastic if the WordPress color picker widget doesn't exist

        jQuery( '#colorpicker' ).farbtastic( '#color' );

    }

});

view raw gistfile1.js The if statement checks whether the new color picker exists as a widget within jQuery UI by first determining whether jQuery.wp is an object, and if so, ensuring that wpColorPicker is a function of that object. If both of these conditions are true we call the new color picker. If not, we load Farbtastic. And that’s it. We used the new WP color picker while still providing older versions of WordPress with a usable fallback. If you’re looking for the entire plugin example you can find it on Github.

Frequently Asked Questions about Upgrading to the New WordPress Color Picker