Add live preview and edit shortcuts for title and subtitle of the website in the WordPress Customizer

WordPress shows two options for entering the title and subtitle of the website in the Customizer under the Website Information section. The standard mode for these settings is refresh , ie if the title is changed, the entire page is reloaded in the customizer preview.

This tutorial explains how you can expand the options with a live preview and edit shortcuts.

Live preview means the immediate display of a change in the preview without having to reload the window. This increases the user-friendliness of the options enormously because users do not have to wait unnecessarily for the preview to load.

Edit shortcuts are a new feature of WordPress 4.7. This denotes the blue icons that are now displayed in the Customizer preview and jump directly to the correct setting with one click. This is also an improvement in the area of ​​usability.

Customizer edit shortcuts

The core standard themes support Live Preview and Edit Shortcuts by default. The necessary code is also contained in underscores, ie if your theme is based on it, these features are already supported automatically.

For themes created elsewhere, I will show below how the live preview and edit shortcuts are technically implemented. The instructions are also great for understanding the code in Underscores and the Twenty * Themes.

Use postMessage for options in the customizer

As already mentioned, WordPress reloads the preview of the website in the customizer when a setting has been changed. This is always the case when the default value refresh is used for the option. As a theme developer, however, you can individually define how the preview should take place for each setting.

So the first thing we're going to do is change the page title and subtitle options. These are defined in the WordPress Core with the setting IDs blogname and blogdescription . With get_setting() we get access to it and can change the transport property from refresh to postMessage .

 $wp_customize->get_setting( 'blogname' )->transport       = 'postMessage'; $wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';

While refresh is the simple implementation, the alternative method postMessage still needs additional code to display the option in the customizer preview without reloading.

Add selective refresh in the customizer

With WordPress 4.5 Selective Refresh was introduced in the Customizer . As the name already explains, there is no longer a complete refresh of the page. Instead, only the area that was manipulated with the option is selectively reloaded.

To implement Selective Refresh, a so-called partial must be created for the option with the add_partial() function.

This is used to determine with a selector where in the theme the option is located. In addition, a callback function is defined that is called to display the updated area after changing the option.

 /** * Adds postMessage support for site title and description for the Customizer. * * @param WP_Customize_Manager $wp_customize The Customizer object. */ function theme_slug_customize_register( $wp_customize ) {   $wp_customize->get_setting( 'blogname' )->transport       = 'postMessage';   $wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';   $wp_customize->selective_refresh->add_partial( 'blogname', array(      'selector' => '.site-title a',      'container_inclusive' => false,      'render_callback' => 'theme_slug_customize_partial_blogname',   ) );   $wp_customize->selective_refresh->add_partial( 'blogdescription', array(      'selector' => '.site-description',      'container_inclusive' => false,      'render_callback' => 'theme_slug_customize_partial_blogdescription',   ) ); } add_action( 'customize_register', 'theme_slug_customize_register' ); /** * Render the site title for the selective refresh partial. */ function theme_slug_customize_partial_blogname() {   bloginfo( 'name' ); } /** * Render the site tagline for the selective refresh partial. */ function theme_slug_customize_partial_blogdescription() {   bloginfo( 'description' ); }

The partial is linked to the option (first parameter blogname ). If the option is changed in the customizer, the HTML element .site-title a (selector theme_slug_customize_partial_blogname() updated with the output of the callback function theme_slug_customize_partial_blogname() .

This eliminates the need to reload the entire page.

In order to make the change more visible in the preview, WordPress hides the edit shortcut when the option is changed and sets a transparency for the area that is changing. Therefore, the page title appears in a light gray when you change it.


Edit shortcuts in the customizer

With WordPress 4.7 and the implementation of Selective Refresh, the customizer now automatically displays the blue edit shortcut icons. Without further action.

How does this work?

Our option for the title now consists of three parts:

  • Setting (the setting itself)
  • Control (display of the setting in the customizer)
  • Partial (display of the setting in the preview)

Both the control and the partial are linked to the setting. As a result, WordPress can now show the blue icon for editing in the Customizer for each partial and link it directly to the respective control.

Selective refresh and the creation of partials are therefore the prerequisites for displaying the edit shortcuts.

Live preview of the options with JavaScript

The second and older way to immediately preview options with postMessage is to use JavaScript.

The preview is manipulated directly with Javascript instead of being completely or selectively updated with PHP code. To implement the method, we therefore have to load an additional JavaScript file in the customizer.

 /** * Binds JS handlers to make the Customizer preview reload changes asynchronously. */ function theme_slug_customize_preview_js() {   wp_enqueue_script( 'theme-slug-customize-preview', get_template_directory_uri() . '/js/customize-preview.js', array( 'customize-preview' ), '20161221', true ); } add_action( 'customize_preview_init', 'theme_slug_customize_preview_js' );

When loading the script, it is important to specify the customize-preview handle as a dependency. This gives us access to the wp.customize object in JavaScript, and if the option is changed, we can manipulate the preview directly with jQuery.

The customize-preview.js:

 /** * Live-update changed settings in real time in the Customizer preview. */ ( function( $ ) {   // Site title.   wp.customize( 'blogname', function( value ) {      value.bind( function( to ) {         $( '.site-title a' ).text( to );      } );   } );   // Site tagline.   wp.customize( 'blogdescription', function( value ) {      value.bind( function( to ) {         $( '.site-description' ).text( to );      } );   } ); } )( jQuery );

The advantage of implementing with JavaScript is that it is much faster. Every change is immediately displayed in the preview. The big disadvantage is that the program logic for the preview has to be duplicated in JavaScript and thus violates the DRY (Don't repeat yourself) principle.

The additional implementation in Javascript is tedious, especially with more complicated options. This is exactly why the Selective Refresh Framework was introduced as a middle ground.

A look at TwentySixteen

What method does TwentySixteen and other standard themes use?

The answer may come as a surprise, but it is both. TwentySixteen includes JavaScript code for immediate viewing as well as the Selective Refresh Framework. Both methods can be combined to take advantage of the speed of JavaScript and the edit shortcuts and transparency of Selective Refresh.

The following pictures show the combination of possibilities:

Change of title only with JavaScript. Every input leads to an immediate manipulation of the preview.


Change of title only with Selective Refresh. The customizer now shows edit shortcuts and makes the changed area transparent. The new title will only be displayed in full if it has been selectively reloaded with PHP.


And now both options are combined, as can also be seen in TwentySixteen.



Especially at the beginning, the various options and terms such as postMessage, Live Preview, Edit Shortcuts, Selective Refresh and Partials can seem very complicated. I hope this tutorial will help you understand the code in TwentySixteen and implement it in your own theme.

If you have any questions, please leave a comment!