Software, Development, and WordPress

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.


  1. Frank

    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

  2. Clark

    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?

    • Clark

      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…)

    • Tom McFarlin

      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 :)).

  3. JohnLionFlow

    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

    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?

    • Tom McFarlin

      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 );`

      ` 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.

  4. Jeremy

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

    • Tom

      Of course! It’s an easy one to overlook :).

  5. John Morrison

    Thanks, the wp_footer() did the trick.

  6. Fakrul Islam

    Default setting are working just fine but my custom settings are not. I have called the wp_footer() in my footer template but it still don’t work :( . Any other solution?

    • Tom

      Have you checked your console to make sure that there aren’t any JavaScript errors?

      Are you using the default transport method (refresh?)

      That’s where I’d start debugging.

  7. Ken Dirschl

    aargh! sure enough it was wp_footer. Thanks Tom!

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑