Learn how to listen for live changes in the WordPress Customizer Preview using JavaScript. Understand the Customizer's parts and structure.

One of the most beautiful functionalities of WordPress is the Customizer, because it allows developers to give a simple way for users to modify themes/plugins appearance and behavior.
However, this beauty has it's own code of conduct.
Let's scratch it a little bit to find out how to listen for changes in the Customizer Preview.

I always like to assume that the reader maybe a beginner, like I was a long time ago, and explain everything from A to Z, so she/he can follow the tutorial or jump to any part according to her/his experience.

For simplicity and practice, as usual 😊, I’ll be using an _s (underscores) generated theme, and call it Customizer Preview 😉. It’s a 1 minute process, so don’t be afraid, type in the Theme Name, download it, and upload it like any other theme under Appearance > Themes > Add New > Upload Theme.
Now you’re all set and we can begin.

Understanding how it’s related

In the functions.php file, search for customizer.php, you’ll find a line like this one:

require get_template_directory() . '/inc/customizer.php';

So the file customizer.php is located in a folder named inc at the root of the theme. If you look inside this file, at the very bottom, you’ll find a little block of code like this one:

/**
 * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
 */
function customizer_preview_customize_preview_js() {
    wp_enqueue_script( 'customizer-preview-customizer', get_template_directory_uri() . '/js/customizer.js', array( 'customize-preview' ), '20151215', true );
}
add_action( 'customize_preview_init', 'customizer_preview_customize_preview_js' );

So here, we have a call for another file customizer.js, located in a folder named js at the root of the theme.
If you take a look inside it, you’ll find a bunch of code allowing us to view the changes we make from the Customizer.

The Customizer’s Parts

When you open the Customizer, you’ll find yourself in front of a screen with two parts: a- the Customizer Pane where the Controls (like Background Image) of a theme are defined in customizer.php
b- the Customizer Preview where the Settings defined in customizer.js act like a bridge between the Controls and their related Partials.

A Partial is simply a particular part of a theme like the header, the body, the footer, the logo, the site title, the tagline… and so on.

As an example, you could have a Control to control the site title color by a Setting linking that color Control to the desired Partial (here the site title).
Now, when you change the color Control in the Pane, the defined Setting for this color Control calls the related Partial in the Preview and tells him to change according to the modifications of his Control.

If you want to dive more into that, you can read about the Customizer Objects in the Theme Handbook.

Listening to changes

At this point, you understand how the Customizer’s parts communicate.
But what if you need to listen for changes in the Preview?
This will be mostly a need if you are a developer or in the process of becoming one 💪👍

Quick quizz. Where do you think the following code will go?
Don’t look under the code before giving an answer 😁

// Listen for any changes in the Customizer Preview.
wp.customize.bind("change", function (setting) {
    // Target the Setting, let's take background_image as an example.
    if (0 === setting.id.indexOf("background_image")) {
        // The background is empty by default.
        // So, we begin by listening to a non empty value,
        // to catch the first change when it happens!
        if (setting._value != "") {
            console.log("I Now Have A Background 🙂")
        } else {
            console.log("I Do Not Have A Background 🙁")
        }
    }
})

What does this code do?
It listen to any 'change' of a defined ( setting ).
Remember, a Setting is a bridge allowing communication between a Control and it’s related Partial.
So when a communication occurs, a change is ongoing and then done!
In the example above, we are listening to any change on the background_image.

Did you try to look for background_image in the generated theme from underscores?!
If you did, you know by now that it’s not here 🤔 and if you didn’t, don’t, you will not find it!
Well, I’ve used it as an example to grab your attention on Core Controls/Settings!
Some Controls/Settings comes with WordPress by default, they can be modified or removed, but this will be for another article.

I didn’t forget, I just delayed it 😈 The code above should go inside customizer.js between a:

(function ($) { ... YES HERE ... } (jQuery));

I really hope that this will be useful.

Note: The background image is a photo by Emiliano Vittoriosi.