Building Theme Color Options with the Customizer

I have almost completely ditched the WordPress Settings API for the Theme Customization API. It’s easier to build, provides a better user experience for my clients/customers, and it helps me focus on keeping things simple.

If you don’t already know how to build the customizer into your theme, you need to check out How to Set Up the WordPress Theme Customizer to get you started and Customizing Client Options Using the Theme Customizer for additional tips.

In this article, I want to show you how to add customizable color options to your theme. It helps you to build your design with intent from the first line of CSS to the last.

Understanding the Concept

Before getting into the code, I want to explain exactly what’s going on.

As you already know (if not, again, read the articles I linked), the customizer allows you to create options and save them to the database. Then you can retrieve those option values and use them however you’d like.

The same is true of the color picker in the customizer. Hex code values are saved to the database. There’s a problem, though. You can’t write PHP in a CSS file and PHP is required to retrieve those values.

No sweat. Instead, color options CSS is added to the <head> of your site using the wp_head() action. We’ll be adding CSS to the document head that overrides theme CSS.

If you have a problem with adding styles to the head, skip down and do this instead.

Your values will be retrieved using PHP, set equal to variables, and we’ll echo those variables in pure CSS. Check it out.

Adding a Color Picker Option to the Customizer

Again, make sure you know how to build the customizer before moving on.

We’ll be adding a section, setting, and control here. Omit the section code and adjust the control values accordingly if you’d like to add your color picker to an existing section.

Let’s get started. Here’s the code you need to add to your customizer function.

// add new section
$wp_customize->add_section( 'bwpy_theme_colors', array(
	'title' => __( 'Theme Colors', 'bwpy' ),
	'priority' => 100,
) );

// add color picker setting
$wp_customize->add_setting( 'link_color', array(
	'default' => '#ff0000'
) );

// add color picker control
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array(
	'label' => 'Link Color',
	'section' => 'bwpy_theme_colors',
	'settings' => 'link_color',
) ) );

Take note of a couple of things here.

First of all, we added a completely new section to the customizer called “Theme Colors.” Depending on what theme you’re working in, you may already have a section called “Colors.” That section is automatically created if your theme supports certain WordPress functionality like “custom backgrounds.”

If you think it makes more sense to add your custom color picker to that section, delete the add_section(), and change the add_control() “section” value to colors.

For more information on customizing the Colors section to welcome your new color picker, read this information.

Secondly, we set a default value for our color picker. It’s red (#ff0000). The color picker will automatically have this color selected now. It is important that you do not use shorthand hex code here. Though we can make it work, let’s shoot for consistency with our future code.

link-color-optionWith the color picker in place, you can now integrate it with your theme.

In this example, we’re going to say that the color picker is going to be used specifically for link colors. Understand that you can build as many color pickers as you need. If your theme uses more than one color, and you want each color to be customizable, you will need to build multiple color pickers named appropriately.

In your theme, you should already have a CSS file with styles written. This is your theme’s default state with no colors adjusted. You used CSS selectors to target site links and give a color. In this case, that color should be red. To put that another way, your theme CSS link color and your color picker default color should match.

So here’s what your theme CSS might look like for links.

a {
	color: #ff0000;

Awesome. Now we’ll use the customizer value to override the theme by adding new CSS to the document head.

The following code does not go inside of your customizer function. It uses its own functions. I like to place mine just below my customizer function, though.

function bwpy_customizer_head_styles() {
	$link_color = get_theme_mod( 'link_color' ); 
	if ( $link_color != '#ff0000' ) :
		<style type="text/css">
			a {
				color: <?php echo $link_color; ?>;
add_action( 'wp_head', 'bwpy_customizer_head_styles' );

The code is simple. We created an add_action() that hooked into the <head> of the theme with a callback function that built out the CSS.

Before building the CSS, we set the saved value of the color picker equal to the variable $link_color. Then we checked the value of $link_color to see if it matched the default theme link color. If so, there’s nothing left to do. The color picker value hasn’t been changed.

However, if $link_color doesn’t match the theme link color, meaning its value has been changed, then we built the <style> tag for the document head and filled it with basic CSS to set the new link color… which is echoed through the variable.

The key here is to make sure your CSS selectors in the theme stylesheet and the CSS selectors added to the head target the same exact elements.

This can get messy.

It’s not uncommon to use the same hex codes multiple times in a stylesheet. While I won’t say it’s sloppy CSS, it can cause headaches in a situation like this.

I find it easier to combine CSS selectors whenever I can. If for some reason I used the same hex code 10 different times as the value of a “color” property, I will have to make sure I find each and every one of them in my theme stylesheet so I can override theme. It’s easy to miss one, which gives the appearance of a broken option in the customizer. Actually, yes… it’s broken.

Take a strategic approach to your theme CSS if you know you’re going to be building customizer color options. Keep it simple and consolidated.

If the same hex code is used for different CSS properties, like color: and background-color:, for example, that’s perfectly fine. Though the hex code is the same, they are applied to different things. So having separate CSS rules is expected. You can’t always consolidate everything.

Also remember that changing just one color may “force” you to create options to change other colors. So this can be a slippery slope if you’re not careful.

An example would be if you provide an option to change the link color. Does your theme also have a different :hover color for links? If so, and you’ve allowed users to change the regular link color, doesn’t it make sense to create a hover color picker as well?

Yes. It does make sense. Here’s a snapshot of the color options I built into the Quota theme for Easy Digital Downloads.


It was absolutely necessary to add additional color pickers when I decided to create options for multiple design elements. This was intentional. If you don’t want to go this far, make sure your approach is intentional as well.

Another Theme Color Customization Option

This method is really straight forward and provides a lot less control for the user. Instead of building a color picker into the theme, you can build any type of control that allows the user to select one single value.

This means select options with a drop down or radio selections would work just fine.

With each selection assigned a value that gets saved to the database when chosen, you can then use that value to add a CSS class to the body of your theme.

function bwpy_body_class_colors( $classes ) {
	if ( get_theme_mod( 'color_option' ) == 'color_option_one' ) :		
		$classes[] = 'color-option-one';		
	elseif ( get_theme_mod( 'color_option' ) == 'color_option_two' ) :		
		$classes[] = 'color-option-two';				
	return $classes;
add_filter( 'body_class', 'bwpy_body_class_colors');

Then in your CSS file, you will need to set all possible options for an element’s color using the body class like so.

// set all links to red
.color-option-one a {
	color: #ff0000;

// set all links to blue
.color-option-two a {
	color: #0000ff;

The difference here is that you’re not necessarily allowing users to customize anything. You’re just allowing them to choose between colors you’ve already chosen. There’s nothing wrong with that at all. Just know which method is right for your theme.

Be smart. Happy coding. 🙂

  1. Hello Sean, thank you for this wonderful tutorial, really helped me a lot on building my own theme, consider me a fan. I just have a one question, I want to add a color option but for gradient, do you have an idea how to it? Thanks.

  2. Hey this helped me a lot. Unfortunately my english is not the best and so i skiped a few sektions and just grabed some code. Now i have the problem that the color picker does not save the color. In the preview everthing looks realy nice. But as soon as i close the customizer dialoge, the color is the same as befor. Nothing has changed.

    What part have i missed ´:-)?

    Hope you can help me.

      • Om my god, sorry for not answering in time. I got the email with the reply notification a few minutes ago.

        Whatever, in the mean time i got the problem solved but i can’t remember how ^^

        Now it works and that’s the only thing that matter. Thanks again for this tutorial and for your answer 🙂

        • Hi Simon, I am also having the same problem – can you explain how you fixed this issue?


  3. Hello,

    Very helpful! However, I’m having a problem.

    a {
    color: ;

    Why can’t I change the ‘a’ to for e.g

    site-navigation {
    background: ;

    (this would be for the navigation background color) when I do this nothing happens although I tried this with ‘body’ and it works.

    Please can you tell me what I am doing wrong?

    Thank you! 😀

    • There’s no reason why you shouldn’t be able to do that. It would work just the same as it does for an anchor tag.

      Note: “site-navigation” in your code above is missing the period or number symbol. Hopefully that’s not the issue.

  4. Great article, I couldn’t get the colors to apply on the front end even though they were changing in the preview but as you mentioned moving the head_styles outside the main function fixed that. Thanks!

  5. I was struggling with this for some time. I have read many tuts, but this is the best yet.
    Thankd man for this tut!

  6. Based on this i’ve build my own theme options. My theme is still in development but is simply awesome. With wp customizer you can change every aspect of your site.

  7. Hello Sean,

    I just want to say a MILLION THANKS on this great tutorial.
    Thank for sharing, because what makes WordPress Great is Great people like you !

    I was looking for a solution to change the hover and active status of menu items.
    I’ve used, function bwpy_customizer_head_styles(), and bundeled in it the main color, the hover color and the active color for menu items.

    I was looking here,
    and i’ve asked David how to apply his solution to a menu and not all the links in the theme. After few hours, my comment was hide, i understood he does’nt want to help (he could reply to say that he don’t know or just to give me a new search direction)… After founding your tutorial, i gave him the link to this page 😉
    Magic, few minutes after, my first comment was back…

    Again, thanks for sharing.

    Have a great coding day 😉

  8. Hi Davis! I’m creating theme color follow your way, but i have a problem, actually i don’t know that is the problem or not. I have so many line css like this

    a ,
    // thousand line below
    color: ;

    will my site slowing down??

Leave a Reply

Your email address will not be published. Required fields are marked *