The WordPress Theme Customizer: When Live Preview Doesn’t Work

I’m currently working on a lengthy set of articles that are intended to provide an in-depth look at the WordPress Theme Customizer. Yes, there has been a lot of material already written on this subject.

Some of the best articles are:

And though I’ve done work with the Theme Customizer in the past, there have been a few gotchas that I’ve found when trying to work with the customer starting from the ground up.

I don’t plan to document them all here, but if you happen to be working with the Theme Customizer and you’re specifically trying to get the “Live Preview” function working and it’s not, perhaps this will help.

WordPress Theme Customizer: Always Include The Footer

Let’s say, for example, that you’re adding a new setting to the existing colors section of your – or any given – WordPress theme.

Before going any further, assume that for the purposes of the code below that I’m using one of WordPress’ provided sections for adding a new setting. Specifically, I’m using the colors section.

And the option that I want to introduce will allow the user to change the color of anchors across the entire site. Additionally, the changes should occur without the page refreshing which means that we’re going to need to hook into customize_preview_init

In order to do this, I’m going to define two functions:

  • tmx_register_theme_customizer which is hooked to customize_register
  • tmx_customizer_live_preview which is hooked to customize_preview_init

You can find these two functions in the following code both of which can live in your functions.php file.

From here, if you launch the Theme Customizer, then you’ll notice that this code will add a color picker to the Theme Customizer that allows the user to select the color they want to apply to the anchor’s throughout their site:

The Theme Customizer Color Picker

The Theme Customizer Color Picker

Now Do It Live!

But there’s a problem: We need to use JavaScript in order to take advantage of the color picker and apply it to the anchors.

Once you include this JavaScript file and then begin working with the color picker you may notice that although it’s supposed to be happening live, nothing is actually happening at all.

Or Not…!

If all is working well for you, then you’re good to go; however, if you’re not seeing any changes, then there’s a very subtle theme development practice that you’re likely missing and that would be the call to wp_footer:

Because we’re register the Theme Customizer JavaScript in the footer – which is how it should be done – the call to wp_footer must be present, so that the customize_preview_init can actually enqueue the JavaScript at the end of the file thus connecting the various components together.

Is That All?

For now, yes – here’s the Gist in its entirety; however, working with the Theme Customizer can be a bit of a mixed bag as it’s something that can actually replace the theme options panel, but it also requires that we re-think how we’re setting up our theme options.

In my upcoming series on the Theme Customizer, I plan to cover exactly that, but if you’ve hit a snag with Live Preview not working with your implementation of the Theme Customizer, check out the provided Gist and the code and see if that helps.

8 Comments

Thanks for the link to my example to use the Customizer in a Theme.
Maybe also interest: WordPress-Theme-Customizer-Custom-Controls and a post about the WordPress Theme Customizer Custom Controls

A little confused here- are you saying that bit of JS you shared is required for live updates to work? My live updates have always ‘just worked’ when I start adding theme customizer options, even ridiculously deep options with dozens of sections. Does this JS do something different?

    I guess the only thing I should mention is that I’m building on _s, which may have this already baked in for me. (just another reason _s rules…)

    The JavaScript explicitly states `postMessage` as the transport, but this won’t make a difference unless the `wp_footer()` call isn’t placed in the `footer` template.

    Based on what you’ve shared, my guess is that you’ve not experienced the problem since _s has that already provided (it’s a best practice to have it, but that doesn’t mean it’s never left out :)).

Hi Tom, thanks for your contributions. I was wondering if you could suggest any other reasons the live refresh wouldn’t be working for me?

Here is the code I’m using https://github.com/John-Lion/Wordpress-customizer

I do already have in footer.php. Also, the default settings are working fine. But the new address section and settings are not refreshing.

Any idea’s?

    At a cursory glance, everything looks good but I would change:

    ` wp_enqueue_script( ‘source_customizer’, get_template_directory_uri() . ‘/js/customizer.js’, array( ‘customize-preview’ ), ’20130508′, true );`
    To

    ` wp_enqueue_script( ‘source_customizer’, get_template_directory_uri() . ‘/js/customizer.js’, array( ‘customize-preview’ ), rand(), true );`

    Until you’re ready for release; otherwise, it’s going to cache an old version of the customizer script.

Thanks — I totally missed the wp_footer / script enqueue issue and pulling my hair out trying to get live preview to work!

Leave a Reply

Name and email address are required. Your email address will not be published.

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>