Mayank Tripathi

Understanding Selective Refresh, PostMessage, and Refresh in the WP Customizer

The WordPress Customizer is a powerful tool that allows developers to provide users with real-time preview changes to themes and settings. Over the years, it has evolved to offer more efficient methods for live previews, such as Selective Refresh and PostMessage. In this blog, we will dive into these options and explore how they work, helping you build more responsive and user-friendly customizations in your themes or plugins.

1. Overview of the WordPress Customizer API

The WordPress Customizer API offers an interface where users can customize their website’s appearance, theme settings, widgets, menus, and more—all while previewing the changes in real time. As a developer, you can add settings, controls, and sections to the Customizer through your theme or plugin.

The three main types of live previewing methods available are:

  • Refresh (default): A full-page refresh after every change.
  • PostMessage: Instant front-end update without refreshing the page.
  • Selective Refresh: A balance between the two, updating only specific elements on the page.

2. PostMessage: Instant Changes Without Reload

PostMessage is a technique that provides real-time changes in the Customizer without the need to reload the page. It uses JavaScript to instantly update elements in the preview panel as users make changes in the Customizer settings.

How PostMessage Works:

When you register a setting in the Customizer, you can specify that it should use postMessage transport for live previews:

$wp_customize->add_setting( 'theme_color', array(
    'default'   => '#ff0000',
    'transport' => 'postMessage', // Set transport to postMessage
) );

After setting the transport to postMessage, you need to hook into the JavaScript that listens for changes. This is where the magic of live updates happens:

wp.customize( 'theme_color', function( value ) {
    value.bind( function( newval ) {
        document.body.style.backgroundColor = newval; // Apply new color in real-time
    });
});
When to Use PostMessage:
  • Performance: When changes are minor and do not require a full-page refresh, such as changing colors, text, or small styles.
  • User Experience: It provides instant feedback, improving the user’s experience.

3. Selective Refresh: The Hybrid Approach

Selective Refresh is a middle-ground between the full-page reload and the instant updates of postMessage. It refreshes only the part of the page that is directly affected by the Customizer changes, offering both efficiency and accuracy.

How Selective Refresh Works:

To enable Selective Refresh for a setting, set the transport property to refresh, and use partial in your theme’s Customizer configuration:

$wp_customize->add_setting( 'header_text', array(
    'default'   => 'Welcome to my site!',
    'transport' => 'postMessage', // For instant updates
) );

$wp_customize->selective_refresh->add_partial( 'header_text_partial', array(
    'selector'        => '.site-header', // Element to be refreshed
    'render_callback' => function() {
        return get_bloginfo( 'name' );
    },
) );

In this example, only the .site-header will be reloaded when the header_text setting is changed, avoiding a full page refresh while still reflecting the updates in the preview.

When to Use Selective Refresh:
  • Complex Structures: When dealing with elements like widgets, menus, or other dynamic content that might require PHP rendering.
  • Partial Updates: If you need a balance between performance and rendering complex data, Selective Refresh provides a good middle ground.

4. When to Use Each Transport Type

  • Full Page Reload (refresh): Use for settings that affect the entire page or when changes rely on server-side data, such as complex PHP logic or database queries.
  • PostMessage: Ideal for instantly updating front-end styles, colors, text changes, and other client-side changes that don’t rely on server-side processing.
  • Selective Refresh: Best for scenarios where specific elements on the page need to be updated without refreshing the entire page. This is especially useful for widgets, menus, and other complex content areas.

5. Other Options in the Customizer API

In addition to PostMessage and Selective Refresh, there are other tools and options to extend the capabilities of the Customizer:

a. Panels and Sections

You can organize Customizer options into Panels (for broader categories) and Sections (for individual groups of settings). For example:

$wp_customize->add_panel( 'header_panel', array(
    'title'    => __( 'Header Options' ),
    'priority' => 10,
) );

$wp_customize->add_section( 'header_layout', array(
    'title'    => __( 'Header Layout' ),
    'panel'    => 'header_panel', // Attach to panel
) );
b. Custom Controls

Sometimes, the default controls (text, radio buttons, checkboxes) aren’t enough. You can create Custom Controls using a combination of PHP and JavaScript. For example, you could create an image uploader control or a complex range slider.

c. Sanitization

Always sanitize user input when registering settings in the Customizer to ensure data integrity and security. WordPress provides functions like sanitize_text_field() and esc_url() to help:

$wp_customize->add_setting( 'footer_text', array(
    'sanitize_callback' => 'sanitize_text_field',
) );
d. Dynamic Previews

You can add dynamic previews by making AJAX requests or triggering changes via JavaScript. This allows you to load data based on user input without overloading the preview.

6. Conclusion

Using the right Customizer transport option can greatly improve both user experience and the efficiency of theme development. Whether it’s instant updates with PostMessage, partial reloads with Selective Refresh, or full-page reloads for complex changes, understanding how to leverage these tools is essential for any WordPress developer.

Incorporating these methods into your themes and plugins ensures a more dynamic and responsive customization experience, making your product more user-friendly and efficient.

Key Takeaways:

  • PostMessage: Instant changes for styles, text, and other front-end updates.
  • Selective Refresh: Efficient reloading of specific elements, perfect for widgets or menus.
  • Full Page Refresh: Use when dealing with server-side data or complex logic.

By choosing the right approach for your customizer settings, you can create a seamless, performance-optimized customization experience for users.

Thank you for reading…
by ~Leaveitblank (Mayank Tripathi)