Custom Controls in the Theme Customizer


In the last article, we explored the advanced controls available in the Theme Customizer, and how to implement them.

We’re going to look at how to create our own custom control, allowing you to choose which Category of Posts are displayed on the home page.

To get started, download version 0.6.0 of our Theme Customizer Example.

Existing Theme Customizer Controls

WordPress supplies several controls, each with their own PHP class. We explored these in the last part of our series:

  • Plain Text Input: WP_Customize_Control
  • Color Picker: WP_Customize_Color_Control
  • File Upload: WP_Customize_Upload_Control
  • Image: WP_Customize_Image_Control
  • Background Image: WP_Customize_Background_Image_Control
  • Header Image: WP_Header_Image_Control

Apart from the Plain Text Input, all Customizer Controls extend the WP_Customize_Control class.

Extending WP_Customize_Control

Each Customizer Control will define some or all of its own class functions to override those supplied by WP_Customize_Control.

For example, WP_Customize_Control contains the following function to output HTML used in the Theme Customizer:

The function detects the $type defined to determine what to output (a plain text input, a checkbox, a radio button, a select dropdown or a dropdown of WordPress Pages).

However, none of the aboves types are useful for WP_Customize_Color_Control, which needs to render a color picker. Because all Customizer Controls extend WP_Customize_Control, the color control can override the above function with its own output:

This is an important concept, which we will now apply when creating our custom control.

Creating a Category Control

At the bottom of functions.php, add the following block of code:

This creates a new Theme Customizer Control called WP_Customize_Category_Control, defining its own render_content() function to override the default render_content() function from WP_Customize_Control.

We initially check if the WP_Customize_Control class exists, as otherwise we’d receive the following error on non-Theme Customizer screens:

Theme Customizer Error

Let’s go through this function to understand what it’s doing.

We use WordPress’ wp_dropdown_categories function to generate a HTML element, listing all Post Categories that have one or more Posts assigned to them.

Next, we add in a data-link parameter to the HTML element. This is specific to the Theme Customizer and important because it tells the Theme Customizer that a change has been made, enabling the Save & Publish button to work.

Finally, we output the select dropdown within a label.

Implementing the Category Control

As with any Theme Customizer control, we need to implement it, so it will display within the Theme Customizer.

Add the following code to the end of the tcx_register_theme_customizer() function, to add a new section to the Theme Customizer:

Next, add the following code right after the code we defined above:

Finally, let’s add our new WP_Customize_Category_Control, binding it to the setting and section above:

Save your functions.php file, and view your Theme Customizer. You should see a new Category section, with a dropdown box labelled Category:

Theme Customizer: Category Dropdown

Choose a category from the dropdown list, and click Save & Publish.

Reading the Category Setting

Right now, the above code doesn’t change the display of our theme. Let’s add some code to index.php, under get_header(), to display a list of Posts:

Make sure you have some Posts assigned to a Category. You’ll then see something like this:

Theme Customizer: Posts Loop

If you’ve followed our other tutorials in this series, you’ll know that we can use get_theme_mod() to get the setting value for a specific Theme Customizer setting.

Modify the above code to read the value of our Category drop down, so we only display Posts assigned to the chosen Category:

If no category has been chosen in the Theme Customizer, all Posts will display, regardless of category.

If a category has been chosen, only Posts assigned to that Category will display.

In our example, I’ve chosen ‘News’ as the Category to display:

Theme Customizer: Posts from News Category


The Theme Customizer is a great alternative to resource-heavy theme option panels or Plugins, and allows site owners to see, in real time, how various settings change the behaviour and style of their WordPress web site.

We've explained the default and custom controls that are available, as well as how a custom control can extend the default Theme Customizer class.

This tutorial has also covered some of the more advanced aspects of using the Theme Customizer, by extending it and allowing you to customize which category of Posts to display on your home page.