Context-Aware Previews within the WordPress Customizer

The WordPress Theme Customization API is an incredibly powerful tool, enabling folks of all skillsets to dive in and customize their websites — if their current theme supports it.

Having worked quite a bit with extending the WordPress Customizer at ThemeBeans, I started production on a newly minted Customizer-dependant commercial plugin, coined Login Designer.

Login Designer leans heavily on the Theme Customization API to bring real-time live previewing to WordPress login page styling. Among other exciting Customizer tidbits, I’ve been experimenting with contextually displayed options, custom edit shortcuts, and context-aware previews.

This post defines exactly what WordPress Customizer context-aware previews are, and why they can lead to a fantastic user experience. Then we’ll dive into real-world code examples from Login Designer.

What exactly are context-area previews?

In the context of the WordPress Customizer, context-aware previews are events triggered by the Customizer, which navigate the preview window.

Let’s look at Login Designer as an example:

The plugin creates and adds a “Login Designer” panel to the current theme’s Customizer instance. Once the Login Designer panel is opened, the context-aware preview event is fired and the preview window loads the login styler.

And to clean everyone up, once a user backs out of the “Login Designer” panel, the preview window returns back to the home page. Pretty cool ‘eh?

Why are they so fantastic?

Let’s think of different ways the application of context-aware previews would work phenomenally in the WordPress Customizer:

  • When editing home page options, the preview shows you the home page
  • When editing portfolio options, you’re looking right at the portfolio
  • When configuring display options for the 404 page, you see it in action

Context-aware previews mitigate the number of clicks a user has to perform when utilizing the Customizer. Users will have to navigate just the Customizer, not the Customizer and the preview window.

Adding your first context-aware preview

There are three steps to adding a context-aware preview to a WordPress theme or plugin — if the plugin leverages the Customizer.

  • Enqueuing the controls javascript, to trigger the action
  • Enqueuing the preview javascript, to listen and perform the action
  • Localizing any page data needed for the scripts

Below is a collection of gists deployed within Login Designer to enqueue the necessary scripts for the plugin’s context-aware previews.

Looking at the gists, you’ll see that I’ve enqueued both the preview and controls scripts accordingly. Then I made Login Designer’s styler page data available to the controls script via localization. That’s it!

Within the controls script, the Customizer is checking on the status of the plugin’s login_designer top-level Customizer panel.

It then communicates with the preview script via login-designer-open-designer, dependent on whether or not the preview window is already on the page requested.

The preview script listens and sends the preview window to the specified location when needed. Simple enough!


Sure, these kind of user experience improvements are not 100% necessary, but they do make WordPress much more exciting and intuitive to work with. In all, WordPress themes and WordPress plugins both can benefit from taking full advantage of the Theme Customization API.

It’s a wonder more developers have not leveraged the WordPress Customizer to improve their products. Why do you think that is?