Logo of studiocrafted which illustrates both design and development through the use of colours above the letter S studiocrafted Sites and Web Applications.

An animated icon to indicate the inner page is loading

WordPress Customizer API

0 words written by Alistair.

The theme customizer API was added to WordPress at 3.4 and does good job of abstracting theme specific options and customisations whilst keeping the end user close to their design and content.

This means a WordPress Administrator can control the content without writing too much code for repetetive tasks.


  • customizer.php - This will be loaded via functions.php in any active theme.
  • jquery.customizer.js - This will be enqueued and loaded only when viewing the customizer.

To load customizer.php in functions.php add this code.

locate_template(get_bloginfo('template_directory').'/resource/php/wordpress/customizer.php', true, true);

We pass 3 parameters to locate_template(), the first is the file we want to locate, the second is if we want to load the template and the third is if we want to require it only once, set this to false for example if we are using locate_template() in a loop.

Whilst here, let's enqueue the JavaScript file from customizer.php.

// Live mods in customizer via the following script
function sc_customizer_script(){
    wp_enqueue_script('sc-app-customizer', get_bloginfo('template_directory').'/resource/js/jquery.customizer.js', array('jquery'), '0.0.1', true);
add_action('customize_preview_init', 'sc_customizer_script');

We're looking for the event hook 'customize_preview_init' here and when it is available our wrapper function of sc_customizer_script() will run. Furthermore, we enqueue the script with wp_enqueue_script() which has 5 available parameters. A unique identifier for the script, the location of the script (we use get_bloginfo('template_directory') to find the working directory and then append the relative path to the file. Parameter three is an array of any dependencies our script has and in this case we specify only jQuery, the next parameter is the version and the final parameter is if we want this script to be loaded in the footer via wp_footer().

Registering Customisations with WordPress

When the jQuery file above was enqueued we used add_action() with the customize_preview_init hook, we'll declare our actual customisations in the same way with a different hook. So let's create a wrapper function and hook it in.

function sc_customizer($wp_customize){

add_action('customize_register', 'sc_customizer');

We will use the following 4 methods inside our function add_panel(), add_section(), add_setting(), add_control() and all of which can only be accessed via the $wp_customize object.

Creating a Panel

First we need to create a panel which will house our sections, controls and corresponding settings.

// Panel will not be shown until a section is added to it
$wp_customize->add_panel('sc_panel_1', array(
	'title'             => __('SC Customisations', 'sc'), // Visible name of panel
	'description'       => __(''Theme customisations.', 'sc'), // Descriptive text for administrators
	'capability'        => 'manage_options', // WordPress user type
	'theme-supports'    => '', // More useful for plugin developers
	'priority'          => '10' // Order within the customizer

Creating a Section

$wp_customize->add_section('sc_theme_logo', array(
	'title'            => __('Logo', 'sc'), // Visible name of section
	'description'      => __('Add a logo to your site.', 'sc'), // Descriptive text for administrators
	'priority'         => '10',
	'panel'            => 'sc_panel_1' // Order within the panel

We're using the add_section() method here on the $wp_customize object here which takes an ID as the first parameter so we have declared "sc_theme_logo" as the ID for this section. Secondly an array of arguments or pairs to be more precise to setup the section the way we want it. There's comments next to the code above for more info.

Adding a Setting

$wp_customize->add_setting('sc_site_logo', array(
	'default'      => get_bloginfo('template_directory').'/resource/img/stock/logo.png',
	'transport'    => 'postMessage' // Post via AJAX or set to default

Adding the Control

$wp_customize->add_control(new WP_Customize_Image_Control($wp_customize, 'sc_site_logo', array(
	'label'          => __('Site Logo', 'sc'), // Visible label
	'section'        => 'sc_theme_logo', // Which section does this control belong to
	'settings'       => 'sc_site_logo',

Live Preview

To utilise 'transport' => 'postMessage' and not the default argument for the setting which was previously declared we can use jQuery and its bind() method to take the return value on the customize() method which is now available to our jquery.customizer.js file. Let's look at it a little closer.

wp.customize('sc_site_logo', function(value){
	$('header h1 a img').attr('src', value);

wp is a JavaScript object available to us when in WP-Admin, we can assign the object to the customize() method and further allocate a specific setting to be watched(sc_site_logo) as a DOM element (I assume this as documentation for WordPress JavaScript is sparse at best). Finally we select the DOM element to have it's value updated from the return value et voila!


At this point we've done pretty much everything we need to hand over configurations to a WordPress adminstrator, that's great! It's useful to know that we can retrieve these settings and use in our themes at any given time. The following snippet is an example of how to do just that.

if(get_theme_mod('sc_site_logo')) :
    echo get_theme_mod('sc_site_logo');
else :
    echo bloginfo('template_directory').'/resource/img/stock/logo.png';

Finally check if there is a value associated with the setting if so echo that otherwise use a default image for the logo example.


Theme configurations are super and in the long run will be a time saver. If you have a starter template for building WordPress themes you could have a skeleton for the customizer also. Some typical scenarios could be:

  • Footer text: Most themes have "Copyright sitename YEAR", substituting this with a site owners personal touch could be cool.
  • Post thumbnails: Create an on/off switch for post thumbnails throughout a theme.
  • Style switcher: Swap in and out certain layout styles, maybe even custom colour pickers for headings and anchor styles.
Logo of studiocrafted which illustrates both design and development through the use of colours above the letter S