Menu Search
Jump to the content X X
SmashingConf London Avatar

We use ad-blockers as well, you know. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf London, dedicated to all things web performance.

The WordPress Customizer – A Theme Developer’s Guide

In case you missed it, release 3.4 included a very exciting new development: the WordPress Customizer for Themes. This allows users to tweak theme settings using a WYSIWYG interface and customize the theme so it includes the colors, fonts, text — and pretty much anything else — they want.

wordpress customizer1
WordPress 3.4 allows you to make extensive customizations to a theme, including colors, fonts, and text.

The purists out there may be throwing their hands up in horror — a WYSIWYG interface! Letting users alter themes themselves! Surely that opens the floodgates for the creation of thousands of ugly, messy WordPress websites? Well, yes, there is a risk of that. But more importantly, the Customizer means that if you’re developing custom themes for client websites, or themes for other developers to use, you have a whole new set of tools to play with.

Further Reading on SmashingMag: Link2

With the Theme Customizer:

  • If you’re developing free or premium themes for others to use, integrating the Customizer will make your themes much more appealing to developers and website owners.
  • If you’re building client websites, you can let your client tweak the template content of their website such as the logo, tagline and contact details in a more intuitive way than by using a theme options page.
  • For both groups, you can let website users and developers make changes without having to rely on widgets or theme options pages — a less risky and less time-consuming approach.

So, let’s start by having a look at what the Theme Customizer is and how it works for the user.

How The Theme Customizer Works For Users Link

The Theme Customizer has been integrated into the Twenty Eleven Theme, so you can try it out using that theme. There’s a great video on the Ottopress blog showing you how the Customizer works with Twenty Eleven7. Using it is simple:

  1. On the “Themes” page, search for and activate the Twenty Eleven Theme.
  2. On the same page, click on the “Customize” link under the current theme’s description.

The “Customize” link is right below the current theme's description on the “Themes” page.8
The “Customize” link is right below the current theme’s description on the “Themes” page. Larger view9.

  1. This brings up the Theme Customizer in the left column, along with a preview of your website on the right.

The theme customizer shown with the twenty eleven theme10
The Customizer options are shown side-by-side with a preview of your website, so you can test the effect of changes. Larger view11.

  1. To make changes, all you have to do is select each of the available options and edit their settings. The options are:
    • Site title and tagline
      Edit the title and tagline of the website without having to go to the “Settings” page.
    • Colors
      In the Twenty Eleven theme, you can only change the color of the header text and website background, but as we’ll see, this can potentially be used for much more.
    • Header image
      Choose from one of the default images or remove the header image altogether.
    • Background image
      Upload an image to use as the background of the website. The image below is what happens when I upload an image of some hang gliders to my website. The image can be tiled but unfortunately doesn’t stretch.

You can set your background image to tile, but not stretch.12
You can set your background image to tile, but not stretch. Larger view13.

    • Navigation
      Select which menu you want to use for the primary navigation of your website.
    • Static Front Page
      Specify whether the front page of the website should be a listing of your latest posts, or a static page of your choosing.
  1. Once you’ve made the changes you want, you must click the “Save & Publish” button. Until this is clicked, none of the changes are reflected in the live website. This means you can play to your heart’s content without your visitors seeing your experiments.

Another really exciting way to use the customizer is when previewing themes. If a theme has the Customizer built in, you can use it to make tweaks before downloading and activating the theme.

This demonstrates the Customizer in action with the Twenty Eleven theme, but what about your own themes? How would you harness this to add more functionality in themes you are selling or developing for clients?

How The Theme Customizer Is Coded Link

The underlying code is actually pretty simple. It consists of two main hooks plus some actions which we’ll look at shortly. To understand how the Customizer is coded and how it can be customized, there are two important things you need to know:

  • The Customizer doesn’t save any changes in the actual theme files, either the template files or the stylesheet. When the website is rendered in a browser, WordPress outputs inline CSS generated by the Theme Customizer to the <head>, which overrides the stylesheet. This means users can easily revert to the standard theme and nothing is lost, but it also means that any changes made using the Customizer aren’t as long-lasting as if you used a child theme, for example.
  • The Customizer uses a set of new functions which you add to the functions.php file. The main functions are:
    • $wp_customize
      An object which is passed to a function you specify in your functions.php file, which effectively activates the Theme Customizer in your theme.
    • customize_register
      The hook that lets you define all aspects of your Theme Customizer: its sections, settings and controls.
    • wp_head
      The hook that outputs CSS based on the options selected by the user, so that changes show up on the live website.

Detailed guidance is available on the Theme Customization API14 page in the WordPress codex.

So let’s take a look at how to implement Customizer in your theme, and how to add your own customization options.

How To Add Customizer To Your Theme Link

1. Activating the Theme Customizer Link

The first stage is to add the Theme Customizer to your theme. I’m going to start with Ari15, a free theme available in the plugin repository that doesn’t have the Theme Customizer included by default. I’m going to add Customizer so we can make some changes:

The Ari theme on my website - white background, green header text, black body text.16
This is how it looks when I activate the Ari theme on my website. Larger view17.

The first step is to add the Theme Customizer with the following code in functions.php:

function Ari_customize_register( $wp_customize ) {
  //All our sections, settings, and controls will be added here
add_action( 'customize_register', 'Ari_customize_register' );

All code to specify how the Theme Customizer will work goes inside the function. You can give the function whatever name you want, but you will have to use that name throughout your code.

When I click the “Customize” link on the “Themes” page, I see the default Theme Customizer:

The Theme Customizer shows default options when you first add it to your website.18
The Theme Customizer shows default options when you first add it to your website. Larger view19.

Now I have the Customizer set up, and I’m ready to add some controls.

2. Letting Users Modify the Theme Colors Link

I’ll start by adding a a section for colors, with controls for the user to change specific colors in the theme. I’ll add this inside the function I’ve already added, with the following code:

$colors = array();
$colors[] = array(
  'default' => '#333',
  'label' => __('Content Text Color', 'Ari')
$colors[] = array(
  'default' => '#88C34B',
  'label' => __('Content Link Color', 'Ari')
foreach( $colors as $color ) {
    $color['slug'], array(
      'default' => $color['default'],
      'type' => 'option', 
      'capability' => 
    new WP_Customize_Color_Control(
      array('label' => $color['label'], 
      'section' => 'colors',
      'settings' => $color['slug'])

What does this code do?

  1. First, it defines the options which the user can change: the color of content text and the color of content link text. For each of these, it defines a default which corresponds to the CSS in the theme’s stylesheet. Doing it this way saves defining the settings for each color option.
  2. It then adds the settings which will enable any changes the user makes in the Theme Customizer to be implemented in the theme. Without this, the new section and controls won’t appear in the Customizer.
  3. Finally, it specifies the control which this setting will customize — new WP_Customize_Color_Control, which activates the color picker that is part of WordPress 3.4 and upwards.

Note that I haven’t had to specify a section as the “Colors” section is automatically created by default when controls are set up that go in it.

After saving functions.php, this is how the Theme Customizer looks:

The “Colors” section is now available in the Theme Customizer.20
The “Colors” section is now available in the Theme Customizer. Larger view21.

As you can see, this isn’t working correctly. I’ve tweaked the link color but it isn’t showing up in the preview. The reason for this is simple: I haven’t set up the connection between our settings and the CSS classes in the theme yet.

I’ll add the relevant code in the <head> section in header.php, just before the closing tag:

  $content_text_color = get_option('content_text_color');
  $content_link_color = get_option('content_link_color');
  #content { color:  <?php echo $content_text_color; ?>; }
  #content a { color:  <?php echo $content_link_color; ?>; }

This defines two variables, one for each option I’ve defined, and then assigns those variables to the relevant CSS selectors. In this case, I’ve just added a setting for all links, but by changing the CSS selectors, you could use this setting for page and post titles, links in different states, website header links and much more.

3. Using the Theme Customizer to Add Content Link

In its default state, the Theme Customizer lets the user amend the website title and tagline. But what if we could use it to amend other content, such as a telephone number displayed in the header? That’s entirely possible, using a similar approach.

I start by adding the relevant options, settings and controls to my function, plus the code to create a custom control not provided by default: a text box:

class Ari_Customize_Textarea_Control extends WP_Customize_Control {
  public $type = 'textarea';
  public function render_content() {

    <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
    <textarea rows="5" style="width:100%;" <?php $this->link(); ?>><?php echo esc_textarea( $this->value() ); ?></textarea>

$wp_customize->add_setting('textarea_setting', array('default' => 'default text',));
$wp_customize->add_control(new Ari_Customize_Textarea_Control($wp_customize, 'textarea_setting', array(
  'label' => 'Telephone number',
  'section' => 'content',
  'settings' => 'textarea_setting',
$wp_customize->add_section('content' , array(
  'title' => __('Content','Ari'),

This code does a few things:

  • It sets a new class of Ari_Customize_Textarea_Control, which extends the built-in WP_Customize_control class enabling us to use our custom control.
  • It defines how the new control will display as a text area.
  • It adds a setting of default to define the content to be customized.
  • It defines the the setting, label, section and content of the custom control.
  • Finally, it sets up a section for our content.

Having done this, the “Content” section appears in our Theme Customizer:

The “Content” section is now available in the Theme Customizer.22
The “Content” section is now available in the Theme Customizer. Larger view23.

As in the previous example, this doesn’t compete the process — I still need to ensure that any content added here is output to the website in the correct location. I add the following code in the relevant place in my header.php file:

<?php echo get_theme_mod( 'textarea_setting', 'default_value' ); ?>

Which adds the phone number to the website:

The phone number now appears, directly below the tagline.24
The phone number now appears, directly below the tagline. Larger view25.

So far I’ve added content and altered the colors. Another feature which users might like is the ability to alter the layout.

4. Adding Options to Alter the Layout Link

For this example, we’ll let users choose whether they want the sidebar on the left or right side of the page. This will also change the CSS, but the Customizer will display a different control from the previous examples: radio buttons. I’ll set up a layout section and add two radio buttons for the user to specify left or right.

$wp_customize->add_setting('sidebar_position', array());
$wp_customize->add_control('sidebar_position', array(
  'label'      => __('Sidebar position', 'Ari'),
  'section'    => 'layout',
  'settings'   => 'sidebar_position',
  'type'       => 'radio',
  'choices'    => array(
    'left'   => 'left',
    'right'  => 'right',
$wp_customize->add_section('layout' , array(
    'title' => __('Layout','Ari'),

This code adds the following:

  1. A setting for the sidebar position radio buttons, followed by a radio button control for that setting.
  2. A section in the Customizer for this to go in.

The next step is to add the output of these settings to our <head> section in order to amend the CSS:

$sidebar_position = get_theme_mod('sidebar_position');
  #sidebar-primary {float:  <?php echo $sidebar_position; ?>;}

ote that here I used get_theme_mod instead of get_option, which I used in the previous example. This is because existing or default WordPress settings are called via get_option(), while added settings are called via get_theme_mod.

This is the effect it has in the Theme Customizer (with some tweaks to the existing theme CSS so the floats work). First, with the sidebar to the left:

The Theme Customizer with our sidebar at the left.26
Larger view27.

And then with the sidebar on the right:

The Theme Customizer with our sidebar at the right.28
Larger view29.

This is a fairly straightforward solution, using the values of the settings in the CSS itself. Another approach would be to use conditional functions to check those values and output custom CSS.

Summary Link

The Theme Customizer is still very new, so its potential hasn’t been fully explored yet. It’ll be worth keeping an eye on new WordPress themes as they come out to see what other developers are doing with the Theme Customizer. This is a capability that developers and vendors of popular themes and theme frameworks are likely to take on board, as it will help non-coders create a website with a customized look and feel. Whether professional WordPress developers will be happy about that is another matter!

I’ve explored a few options here but there are more possibilities:

  • Add an upload control so that website owners can upload their logo or mugshot,
  • Add checkboxes to specify whether content is displayed or CSS is switched on,
  • Take the layout options further by allowing the user to specify whether the website will make use of media queries,
  • Add more custom colors so website owners can fully customize their website’s look,
  • Add radio buttons to select custom fonts.

And the list goes on! Please use the comments section below to post examples of how you’re using the Theme Customizer or how you’ve seen it in action.


Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28
  29. 29

↑ Back to top Tweet itShare on Facebook

Rachel is a freelance web designer and writer specialising in mobile and responsive WordPress development. She's the author of 'Mobile WordPress Development', a comprehensive guide to making yourWordPress site mobile-friendly, published by Packt, and also author of 'WordPress Pushing the Limits', published by Wiley.

  1. 1

    Thanks for this Rachel! I’d been looking into implementing this for a theme I’m developing for a client. This’ll make changes for them into a snap! One question, if they change themes down the road, is the meta data still stored and accessible in the database?

    • 2

      Rachel McCollin

      March 7, 2013 4:51 am

      Thanks David, glad to be of help! The method outlined above saves the data to the wp_options table because I’ve used ‘type’ => ‘option’ in my settings. This means the data is stored in the database.

      This has its advantages for users moving to new themes, but also has disadvantages in that a user switching to a completely new theme who doesn’t want to use these options will still have them in the database – in which case you may need an ininstall function to remove them.

      This is covered in more detail in Otto’s post at

      I hope that helps!

  2. 3

    Carlo Rizzante

    March 6, 2013 3:09 am

    Sweet, it seems that there is potential in it.

    But do I understand correctly that each option is stored in the database in fact as a single entry? If so, for theme which a full load of tweaks and options, I would avoid the Customizer or the database will quickly clutter up. I still prefer to go for my own custom code which uses one single array for countless options. I’ll keep an eye open on the Customizer to see how it evolves.

    Thanks for the article, Rachel.

    • 4

      Rachel McCollin

      March 7, 2013 4:54 am

      Each option is stored in an array against an entity, so for example above where I’ve used textarea_setting, there would be multiple values stored in an array against that entry in the database – so not quite as many database entries as you might think.

      I think the theme customizer has some real potential but that will be realised over time as people come up with ways to adapt it and do interesting things with it. In many cases theme options will still be the most appropriate method for some themes, but I’m interested too to see how the cutomizer evolves.

  3. 5

    David Knight

    March 8, 2013 11:18 am


    Good tutorial but you have an issue in your render_content function in the new class you’ve made.

    The textarea close tag has a space in it (text area, should be textarea) which causes the customizer to stop rendering beyond the content section without any error being output. Obviously needs updating in your example.

    Also, you don’t need a comma after the last item in an array.

    Thanks! =)

    • 6

      David Knight is right, the code for adding “text content” is wrong (closing tag of the textarea). Once removing the space between “text” and “area”, the code works flawlessly.

      Great post though, I’ve been meaning to learn how to do this for years!

  4. 7

    Great article!

  5. 8

    Bill Gilmore

    May 11, 2013 6:54 am

    Thank you for a seriously quality tutorial, and thanks for making it easy to understand. I tried to follow this on a few other sites and the terminology was far too technical. Cheers Rachael

  6. 9

    Bill Gilmore

    May 13, 2013 7:51 am

    Hi, I have been experimenting on a new theme i’m building. Unfortunately this ‘theme customisation’ seems to get confused with ‘add_theme_support’ custom background and headers.

    Is there a way to stop ‘theme customisation’ from displaying these options? I want the end users to be able to use the functionality of ‘add_theme_support’ custom background and headers, but not from the ‘theme customisation’ control area (as the controls don’t work from there). Any feedback would be great appreciated and thanks for the great tutorial again

  7. 10

    Hamid Faraji

    May 21, 2013 10:29 pm

    Thank You For This Artcle.Amazing Toturiall. ;)

  8. 11

    Jakub McJabbo

    June 3, 2013 5:14 am

    Hi. Very usefull tutorial, thanks for it. But i have one problem – Color changing works well, but the content didn’t. When I add exact same code in my functions.php i got this error message:

    Fatal error: Class ‘WP_Customize_Control’ not found in /data/web/virtuals/22236/virtual/www/subdom/wp-test-2/wp-content/themes/wp-test-2/functions.php on line 71

    And i did copy/paste it (without textarea error, where you have /text area instead /textarea – you shall fix it) and it doesn’t work. Anybody can help?

    • 12

      Franco Musso

      June 24, 2013 4:22 am

      I struggled with this also.
      This is due to the location of the class because you’re trying to extend the WP_Customize_Control class, which only gets loaded and defined when you’re actually using the customizer.
      The class should be placed within the Ari_customize_register function.
      I found that after much head scratching over at ottopress_com/2012/making-a-custom-control-for-the-theme-customizer/
      I hope that helps,

  9. 13

    Hello Rachel, could you possible help me with this?

    Quickly –

    I’m trying to figure out “How to hide child options when parent option isn’t selected. (in WordPress customizer)


    More Details –

    There are few bullet points (Parent Options); each might have several child options under it.

    Right now what happens is all parents and child options are visible by default when I create a new custom control.

    Ex –

    # Bullet 1
    # Bullet 2 (selected)
    # Bullet 3


    And what I want to do is similar to what happens in default “Static Front Page” customizer setting – The child options should be visible ONLY of the selected parent option.

    Ex –

    # Bullet 1
    # Bullet 2 (selected)
    # Bullet 3


    Video –

    (Video is taken from – In WordPress Dashboard, Under Appearance -> Themes -> Customize)

    Any help would be greatly appreciated.

  10. 14

    Hi Rachel,

    Great article and thank you! Is there a way to sort the colors arrays to display in a certain order? For example, I have multiple color options for navigation text, navigation hover, links, body text… but the order they are displayed in the customizer is random.


  11. 15

    Hello, I guess that my question will be of interest for many: I wonder which is the way/widget/plugin to customize the main page layout of your WordPress theme in order to simply add space under the slider and above the widget area to display a featured article? Thank you.

  12. 16

    Okay, I am going nuts and unable to figure this one out. The first two options in the colors array are flipped in order. Instead of coming out with the Text option first, followed by the Link option, it comes out Link, then Text. I can print the values out in the foreach loop in the correct order, but as soon as I feed it through $wp_customize, the first two flip. Going seriously nuts here. This doesn’t seem possible. If I reverse the two first two options in the array, it then comes out in the correct order. Everything past the first two in the array is outputted fine.

  13. 17

    Where is the code in part 3 supposed to go?

    Doesn’t some code need to go in the index.php?

  14. 18


    why do you do this:

    #content { color: ; }
    #content a { color: ; }

    why not call the colors directly and save some queries?

  15. 19

    You got a typo html code under paragraph 3.
    should be I’ve spent 20m trying to figure out error in wordpress :D

  16. 20

    Example 3 typo….this one caused a bit of headache until i noticed one of the closetags :P

    “<textarea rows="5" style="width:100%;" link(); ?>>value() ); ?>”

    “” ?

    try “”.

    instantly fixed all of the headache that i was havin.

  17. 23

    Great tutorial! Thanks for this.

  18. 24

    I was having a think about this and thought it would be good to not load the old styles in the first place. I’ve been through most of the mediaelement.js library and can’t find the ugly CSS that is loading for that first 0.3 seconds. Do you have any idea where it would be? Looking player for my site.

  19. 25

    Daniel Keith

    June 24, 2015 8:00 am

    Hi there,
    Adding content using the Customizer is really a great idea. No doubt, this update had made very easy to customize a website.

    Thanks for sharing your professional experience.


↑ Back to top