How To Utilize Theme Customization API To Enhance Your Theme’s Capability In Dashboard


No matter you’re a seasoned developer or just a beginner getting started with WordPress, as your website grows you’ll most likely be compelled to adjust your theme, in order to meet your website developing needs. For instance, you may need to make tweaks to your theme’s settings, color scheme, etc. And to accomplish such objective, you’ll probably want to have better control over your website theme structure. In that case, WordPress Theme Customization API is exactly what you need. It is a useful and easy way to operate WP Theme Customization Screen (image via shutterstock).

Img-A Utilize Theme Customization API

One way of encouraging online surfers make a visit to your website is to present them with an attractive and captivating design – they can’t take their eyes off. In simple words, it is very important to have a website design that easily catches your visitors’ fancy. But, making changes to the theme as per the varying web trends and users needs can give theme developers a hard time. However, having an easy to manage theme customization screen can make the process of theme customization a breeze.

Luckily, the Theme Customization API allows you to tweak your WordPress theme customization admin screen with ease, by adding more customization options to the theme.

Assuming that you already have a little knowledge of developing a WordPress theme, through this post, I will like to provide you with a brief introduction on the WordPress Theme Customization API. Additionally, you’ll learn about how you can utilize it to enhance your theme’s capability in dashboard.

An Overview of Theme Customization API

The Theme Customization API isn’t a new feature and has been available in WordPress for over two years now. It was introduced with the release of WordPress version 3.4 and enables developers to customize as well as add controls to the theme customization screen (also referred to as Theme Customizer) of WP powered sites. The best aspect about “Theme Customizer” is that it lets developers to make tweak to their theme’s settings and preview them in real-time. In fact, it even allows an end-user (the one having administrative capabilities) to have a real-time update of the changes that were introduced into their theme.

In nutshell, the Theme Customizer saves developers and users from switching in between any WP theme’s dashboard and front-end to see the results of the tweaks that have been made.

How to Utilize Theme Customization API?

The Theme Customization API offers enhanced theme control, thereby allowing theme developers to add their own options to the theme customization screen (or theme customizer) from the WordPress dashboard. For this purpose, however, developers require to use at least 2 hooks such as:


: It lets you define new sections, settings, and controls within the Theme Customizer.


: It allows to output custom-generated CSS, in order to ensure that your changes are correctly visible on the live site.

Now let us discuss about how you can use both these hooks to define settings, controls, etc.

within your theme.

Img-B Utilize Theme Customization API

1. Defining Settings, Controls, Etc. in Theme Customization Admin Screen

In order to define any new theme sections, controls or settings, you will first need to register them using the customize_register action hook. Take a look at the following code snippet to get an idea of how you’ll have to define this hook:

function mytheme_customize_register( $wp_customize ) {

//All your sections, settings, and controls will come here


add_action( ‘customize_register’, ‘mytheme_customize_register’ );

As you can see in the above code, we are creating a function mytheme1_customize_register( ), to define our set of custom sections, settings, etc. Next, $wp_customize is passed as an object to the function, and its methods are used for performing all customizations.

1.1. Adding a New Setting

In order to obtain or set your theme settings, WordPress theme_mod features are used. So, when adding a new setting to your website theme customizer, you simply have to call the $wp_customize->add_setting() method. For example, let us write a code that illustrate how you can add a new theme setting: header_textcolor (this setting will allow you to change the color via the customizer):

$wp_customize->add_setting( ‘header_textcolor’ , array(

‘default’ => ‘#ffffff’,

‘transport’ => ‘refresh’,

// this is optional

) );

1.2. Adding a New Section

Sections are also called as group of options. All your new controls needs to defined within your theme sections. Even though, you can choose to add your theme’s settings to current default sections, but let us see an example, demonstrating how you can add a new section to your Theme Customizer.

For doing so, the very first thing you need to do is to call the $wp_customize->add_section() method (within the ‘customize_register’ action) as shown below:

$wp_customize->add_section( ‘mytheme_new_section_name’ , array(

‘title’ => __( ‘Visible Section Name’, ‘mytheme’ ),

‘priority’ => 30,

) );

Note: By default, WordPress comes with some built-in sections. In case you need to use the existing sections, you don’t have to declare them using the add_section() function. And rather you can simply refer to the built-in ones by name. Here are a few built-in sections you should be aware of:

title_tagline – Helps to set website Title & Tagline

colors – Allows to Colors

header_image – Header Image

background_image – Background Image

nav – Navigation

static_front_page – Static Front Page

Img-C Utilize Theme Customization API

1.3. Adding a New Control

A control on the Theme Customizer page (or Theme Customization admin screen) serves two purposes:

It helps website admins to manipulate any setting,
It binds some existing setting to already existing section.

As we had discussed above, controls ought to be defined within a theme section, which requires you to call the method $wp_customize->add_control().

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, ‘link_color’, array(

‘label’ => __( ‘Header Color’, ‘mytheme’ ),

‘section’ => ‘your_section_id’,

‘settings’ => ‘your_setting_id’,

) ) );

Controls (or Controllers) comes with several options, in our case, we’re using a control that has an option that need you to pass it another class: WP_Customize_Color_Control().

2. Generating Live CSS

Img-D Utilize Theme Customization API

In this step, you are required to fetch the setting (header_textcolor) and implement CSS to make it visible within your theme customizer. In case you’ve defined the setting within a ‘customize_register’ action (as discussed above), then you can easily get the values for your settings with get_theme_mod() method.

Below is an example that will demonstrate how you can have a setting named ‘header_color’:

$wp_customize->add_setting( ‘header_color’ , array(

‘default’ => ‘#ffffff’,

‘transport’ => ‘refresh’,

) );

Next, you simply need to output the css into your header as follows:

function mytheme_customize_css()





add_action( ‘wp_head’, ‘mytheme_customize_css’);

Once the above code is executed, when you’ll access your theme’s page source you would notice that your header contains the following snippet:

Wrapping Up!

This post is just a basic tutorial intended to help theme developers become familiar with the WordPress Theme Customization API. In addition, it serves as a guide that will help you learn about the basics of: how you can make tweaks to any WordPress theme Customization admin screen.

About Author: Emily Heming is a professional WordPress developer for a leading PSD to WordPress conversion company. She also provides conversion services like HTML to WordPress theme and many more. She has served many worpress companies helping them in developing user-friendly website. So feel free to contact her.


Related posts