1. Code
  2. Plugins

How to Use WordPress Color Picker API

Read Time:8 minsLanguages:

When the WordPress team releases a new version, they introduce some new features not only for users but for developers, as well. WordPress offers a lot of tools that make it easier to develop new fantastic themes or plugins.

One of the latest API available for WordPress developers is the new Color Picker; this feature allows to replace the standard text field with a nice and user friendly color picker.

In this tutorial, I’m going to show you how add the color picker inside your WordPress project. Let's get started.

Why It Can Be Useful

There are some interesting reasons why WordPress developers should implement colors choice using the new picker API:

For Users

  • It provides a quicker and easier way to choose a color.
  • Users don't have to worry about what format of color they have to type – hexadecimal, RBG and so on.
  • Generally speaking, it provides an overall better user experience.

For Developers

  • Your dashboard pages will be integrated with the WordPress user interface.
  • It provides an easier input validation of the value of the color field.
  • It results in a more professional final product because it's using native controls.

After we cover some of the main aspects of WordPress Color Picker, let’s add it inside our plugin or theme.

Include Color Picker Assets

Before continuing, I have to specify that Color Picker API was introduced with WordPress version 3.5 so in order to work through this tutorial, then make sure you have release 3.5 or later installed.

To add the color picker, you simply include a jQuery file and stylesheet file. The code lines below show you how to do that.

Note that when we have included the custom-script.js with wp-color-picker dependency. Now you can apply the color picker to your text fields inside your jQuery file.

Creating a Plugin That Uses The WordPress Color Picker

At this point, it's time to show how integrate the Color Picker inside a real plugin.

Here's what we are going to cover:

  • How to add a dashboard option page that simulates a theme settings page.
  • How to add settings fields that are prepared for the Color Picker.
  • How to validate and save inputs.

Step 1

Once you have set up your plugin inside your WordPress wp-content/plugins folder we are ready to get started. The image below shows how I've structured the plugin for this tutorial. 

Plugin Structure

Step 2

Inside color-picker-plugin.php file, write the comments with plugin info and create a new PHP class called CPA_Theme_Options. The code below shows all class methods we are going to implements step-by-step.

Step 3

First, let's implement the class constructor. The code below shows what the plugin will do when a new instance will be created.

It will:

  • add a new options page under the Setting section of WordPress admin menu
  • register settings fields inside the options page
  • add CSS stylesheet for the WordPress Color Picker
  • add a custom JavaScript file that calls Color Picker
  • set the options attribute with settings saved.

Step 4

The next step covers how to add the options page and how to display it.

Note that we have already written - inside the display_page() method - the code that will add the form, the fields and the submit button for registering page options.

Step 5

In this step we are going to implement the methods which will register and display two settings fields: Blog Title field and Background Color field. Both fields belong to the Theme Options section.

Step 6

This steps is focused on validation. The code below show how to validate the two fields before saving them.

If the user tries to insert the color code manually, the Color Picker notifies him or her that s/he has typed a invalid value on the submission form; however, color - though it may be wrong - will still be saved. The check_color() function takes care to validate the color input.

Step 7

This is the final step where we are going to include our JavaScript file that convert a simple text field in an useful color picker.

Let's create the jquery.custom.js file.

If you try to activate the plugin, you should get an dashboard page with all fields like in the image shown below:

Final Admin Page

That's It!

In this tutorial, you have learned how to include the new Color Picker powered by WordPress. In the plugin demo I've shown you how to integrate the color picker in a real plugin but you can use the API where you need such as inside a meta box, a widget form and so on.

The Color Picker works with WordPress 3.5+, but if a user has a previous version your code will work. Make sure to validate each color input using the check_color() method shown in Step 6.

Now your plugins or themes will be more powerful and user friendly.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.