When I add a setting to a ClassicPress theme, I start by asking what has to change in the preview. A color picker feels better when you can see the color as you move it. A sidebar setting may change which template loads and what markup it produces. Those two settings call for different preview behavior.

I start with refresh and use postMessage where the immediate feedback is worth maintaining a small JavaScript handler. Both let you preview a pending change before publishing it. The transport changes how the preview updates. It doesn’t change how you register, sanitize, or save the setting.

Use refresh when PHP owns the layout

Imagine a setting that switches between a sidebar and a full-width page. If the full-width template leaves out the sidebar entirely, switching back involves more than changing a CSS class. The sidebar markup and widgets have to be rendered again. I’d keep that setting on refresh, which is the default. That way, the preview uses the same PHP templates as the live site.

If reloading the entire preview is distracting and PHP can render the change as a self-contained section, consider selective refresh. It can replace that section using server-rendered markup. It’s worth a look when you need PHP to stay in charge but only part of the page needs updating.

Use postMessage for a footer credit

Here’s a complete preview example for plain footer text. Register the setting and control in your theme’s functions.php. Replace the example text domain with your theme’s own.

add_action( 'customize_register', function ( $customize ) {
    $customize->add_section( 'example_footer', array(
        'title' => __( 'Footer', 'example-theme' ),
    ) );

    $customize->add_setting( 'example_footer_credit', array(
        'default'           => '',
        'sanitize_callback' => 'sanitize_text_field',
        'transport'         => 'postMessage',
    ) );

    $customize->add_control( 'example_footer_credit', array(
        'section' => 'example_footer',
        'label'   => __( 'Footer credit', 'example-theme' ),
        'type'    => 'text',
    ) );
} );

add_action( 'customize_preview_init', function () {
    wp_enqueue_script(
        'example-customizer-preview',
        get_theme_file_uri( 'assets/js/customizer-preview.js' ),
        array( 'customize-preview' ),
        wp_get_theme()->get( 'Version' ),
        true
    );
} );

Render the saved value in the footer template. Keep the element present when the credit is empty so the preview script can still find it.

<span id="example-footer-credit"><?php
    echo esc_html( get_theme_mod( 'example_footer_credit', '' ) );
?></span>

Save this as assets/js/customizer-preview.js in the theme:

wp.customize('example_footer_credit', function (setting) {
    setting.bind(function (value) {
        var credit = document.getElementById('example-footer-credit');
        if (credit) {
            credit.textContent = value;
        }
    });
});

The JavaScript treats the value as text, just as the PHP template escapes it for HTML. In the Customizer, type a new credit and clear it again. Both should update without reloading the preview. Publish a normal credit and open the site outside the Customizer to check the PHP output. Finally, try an unsaved edit and close the Customizer without publishing. The live site should still show the saved credit.

If the control changes but the preview stays still, check that the script loaded inside the preview frame and that the setting and element IDs match. Setting postMessage stops the normal reload, so the handler has to do the visible work.

ClassicPress setting implementation · Customizer handbook on live preview and selective refresh