BugWP logo BugWP
Back to Community
Home / Community / Plugin → Kirki customizer framework

How to Use Conditional Logic and Live Preview in the Kirki Customizer Framework

23 threads Sep 7, 2025 Plugin → Kirki customizer framework

Content

Working with the WordPress Customizer can be incredibly powerful, but managing complex conditional logic and achieving a smooth, live preview can be challenging. The Kirki Customizer Framework provides tools to make this easier, but understanding how to implement them is key. This guide covers the most common methods for showing/hiding controls and updating the preview without a full page reload.

The Core Concept: Conditional Controls

Many theme developers need to show or hide certain settings based on the value of another setting. For example, you might want to display a color picker only if a user has checked a "Customize Colors" toggle. Kirki simplifies this with the 'required' argument.

How to Implement the 'required' Argument

The 'required' argument allows you to define conditions that must be met for a control to be visible. It uses an array to specify the setting, a comparison operator, and the value to compare against.

$controls[] = array(
    'type'        => 'select',
    'setting'     => 'my_select_setting',
    'label'       => __( 'Select Demo', 'textdomain' ),
    'section'     => 'my_section',
    'default'     => 'option-1',
    'choices'     => array(
        'option-1' => __( 'Option 1', 'kirki' ),
        'option-2' => __( 'Option 2', 'kirki' ),
    ),
    'required' => array(
        array(
            'setting'  => 'my_toggle_setting', // The setting to check
            'operator' => '==',                // Comparison operator (==, !=, etc.)
            'value'    => true,                // The value to compare against
        ),
    ),
);

In this example, the select control will only appear if the toggle control with the setting my_toggle_setting is checked (has a value of true).

Beyond the Basics: Custom Active Callbacks

While the 'required' argument is powerful, some conditions are too complex for its built-in comparisons. For instance, you might want to show a control only if a specific widget is active. The 'Kirki Customizer Framework' team has confirmed that Kirki does not have a built-in solution for this.

In such cases, you must use the native WordPress Customizer API and write a custom active callback function using 'active_callback'.

function my_custom_active_callback() {
    // Perform your complex logic here
    return ( is_active_widget( '', '', 'my-widget-id' ) ) ? true : false;
}

// In your control array
'active_callback' => 'my_custom_active_callback',

You may also need to write custom JavaScript to handle the live updating of these complex conditions in the Customizer preview.

Achieving a Live Preview (Without a Refresh)

A common frustration is the Customizer preview refreshing entirely when a simple change is made, causing you to lose your scroll position or state. The solution is to use the 'transport' method 'postMessage' and then handle the live update with JavaScript.

Step 1: Set the transport method for your control to 'postMessage'.

'transport' => 'postMessage',

Step 2: Enqueue a custom JavaScript file for the Customizer preview and write a script to listen for changes. For example, to change a body class based on a radio control:

wp.customize( 'theme_layout_control', function( value ) {
    value.bind( function( new_layout ) {
        // Remove any existing layout classes
        var bodyClasses = jQuery( 'body' ).attr( 'class' );
        bodyClasses = bodyClasses.replace( /layout-[a-zA-Z0-9_-]*/g, '' );
        
        // Add the new class based on the selected value
        jQuery( 'body' ).attr( 'class', bodyClasses ).addClass( 'layout-' + new_layout );
    } );
} );

Important Limitations to Know

  • Repeater Fields: Conditional logic ('required') can be applied to hide an entire repeater control, but it cannot be used on individual sub-fields within a repeater.
  • Partial Refresh: For more complex live previews, like updating a background color, you can use the 'partial_refresh' argument. This is more advanced but offers greater control over what part of the preview is updated.

Conclusion

By combining Kirki's 'required' argument for simple conditions, WordPress's 'active_callback' for complex logic, and JavaScript with 'postMessage' for live previews, you can create a highly dynamic and user-friendly Customizer experience. Remember that some advanced scenarios may require custom JavaScript solutions beyond Kirki's built-in features.

Related Support Threads Support