WordPress Theme Customization API

Understanding The Use Of WordPress Theme Customization API For Developers

WordPress is a super easy content management system that comes loaded with many useful features that gives users the ability to customize their websites as they deem perfect. The Theme Customization API is one such feature that makes theme customization a fun and easy task for WordPress users. Introduced with WordPress version 3.4, the Customization API renders webmasters the ability to make changes to any WordPress theme and preview them in real time. Before working with Theme Customization API you must need to be familiar with WordPress Theme Customization Features.

If you have been planning on making to your WordPress website theme, then the Theme Customization API can provide you with several possibilities to make the required tweaks to the theme and check how they look, before publishing them on your live website. Through this post, I’ll make you learn how you can use the WordPress Theme Customization API feature to improve your theme’s capability.

Note: This post requires knowledge about the theme and plugin development, and familiarity of the WordPress Settings API.

Understanding Basics of WordPress Theme Customization API

The Theme Customization API lets developers add a “Customizer Page” to a WordPress theme, so as to give them the capability to change the look and feel of the theme. Additionally, the Customizer page enables developers to edit or add settings of the theme.

Essentially, the Customization API enables theme authors/developers to create more options for the theme settings page. Plus, it allows adding more controls to the “Customize” screen – that is positioned under the Appearance menu n a WordPress website admin dashboard screen.

For instance, developers or site administrators can change their theme color scheme, headings, etc. from the Theme Customization screen (or Theme Customizer Page). Also, they can view how their changes look in the Customizer page.

Now prior to understanding how the Theme Customization API works, let us have a look at the various default theme settings as well as controls that can be found on the Customizer Page:

  • You can set your theme’s title and tag line using the default Set Title and Tagline sections.
  • Change the color of your theme’s background using the built-in Background Color sections.
  • Upload any image to the theme header area using the Header Image sections and much more.

How WordPress Theme Customizer Works?

WordPress Theme Customizer is categorized into three different components, namely: section, setting and control. Let us take a look at all these components one by one:

  • Section: This component displays a group of settings. All of your newly created theme settings as well as controls need to be embedded in the Theme Customization screen section area. Or else, you can add them to the default sections.
  • Setting: It showcases all the options of a theme customization screen.
  • Control: This component is basically an HTML form element available on the Theme Customizer page that gives WordPress website administrators the wherewithal to alter any particular theme setting while previewing it.

Remember that in order to add your own custom options in the Theme Customizer page of your site, you will need to make use of the following two hooks:

  • customize_register: This will allow to define new sections, settings, and controls on your site’s theme customization screen.
  • wp_head: It helps in displaying the output of the custom-generated CSS.

How To Use The WordPress Theme Customization API?

Let us now discuss about the process you need to follow for utilizing the Theme Customization API feature using the following steps:

Step 1 – Registering a Theme Customizer Page

Whether you would like to add/remove/modify any customizer object (i.e. new settings or controls or sections), you’ll have to first register them using the action hook: customize_register. In our case, we want to add a new customizer objects. To do so, you just need to add the below mentioned line of code in your theme’s function file (i.e. functions.php):

WordPress Theme Customization API

The code is creating a function named yourthemename_customize_register() that will  let you add your custom settings, sections, etc. to the WordPress theme customizer manager (i.e. $wp_customize). Your theme customizer manager methods can be used to make any sort of customizations to the theme customization page. Once you’ve completed customizing that page, simply define your new settings, sections and controls, as follows:

  • Defining a New Theme Setting: In order to add any new setting(s) to the theme customizer (or customization) page, you just need to call the ‘$wp_customize->add_setting()’ method. Let’s take an example to understand how you can add a new setting that changes the text color of your theme’s header part:

The “header_textcolor” setting defined in the code above will help in changing the color of the header area in your theme to red.

  • Defining a New Section: All your new controls will be added to the section of your Theme Customization Page. But, you’ll first have to define a new section first, by calling the “$wp_customize->add_section()” method using the following code:

Remember that there are several built in sections in a WordPress theme. If you would like to add your new controls to any one of default sections, you won’t need to call the add_section() function as discussed earlier; rather you can use the built-in sections by name. For example, the built-in section named title_tagline will help in modifying the title and tagline of your WordPress theme. Or else, you can alter the navigation menu using the nav built-in section and so on.

  • Defining a New Control: Lastly, in order to define a new control simply call the $wp_customize->add_control() method. Here’s a code snippet that will demonstrate how you can add a new control to any particular section of your theme:

Step 2 – Creating Live CSS

The second and the last step requires you to get access to the setting (in our case the header_textcolor setting), which is followed by outputting a few CSS styles to that setting.

When defining new settings for the theme, we used the ‘customize_register’ action to add the settings. And so, to fetch the values of those settings, you just need to use the get_theme_mod() method as shown in the example below:

The code will create a setting with the name as ‘header_color’. Next, we need to write a code to add the CSS into your theme’s header area:

When the above code gets executed, the color of the header will be changed to red. But, what if you would like to change the default color of the header to something else, say gray. To accomplish such an objective, simply open up the Theme Customizer Page and replace the #ff0000 hex value to #d3d3d3 as you can see in the code given below:


WordPress Theme Customization API has proved a useful resource for theme authors and developers alike, as it gives them the ability to customize a WP theme according to their needs. The customization API provides access to several settings, sections and controls to perform customizations.

But, what if you wish to add your own custom settings or controls to your WordPress theme customization screen? Reading this post will help you provide basic understanding of the Theme Customization screen, and how you can define your choice of settings, controls, etc. to it.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.