Adding Dynamic Options to the WordPress Customiser

Content:

The WordPress customiser is a great way to add customisation options to your website.

The flexibility of the customiser allows you to add pretty much any customisation option you can imagine for your website, provided you can code it.

What it’s missing, however, is an out-of-the-box way to show/hide options programatically, based on other values.

For example, an option to change text colour would only make sense if the option to display the text is enabled, so it would be beneficial to only show the option in this case.

Fortunately, the customiser itself is also flexible, and with a bit of code, it’s possible to make the options shown in the customiser dynamic.

How the Customiser Works

To understand what needs to be done to make options dynamic, it’s worth looking into the way the customiser works.

The main functionality is powered by PHP, either in the functions.php file, or a separate PHP file depending on your preference.

This contains the code to create panels, sections and settings.

By default, the customiser view refreshes the window when a setting is changed. Using the customize_preview_init hook, it’s possible to dynamically update these values instead, by loading a JS file.

A second hook, customize_controls_enqueue_scripts, allows the content displayed in the customiser pane to be changed from the data supplied by PHP. This can be done dynamically, again by loading a JS file.

It’s the functionality of this second hook that we’re interested in.

Setting Up the Action

There are two parts to using this hook.

The first part is to load a JS file whenever the hook is triggered. The second part is to alter the customiser options dynamically in the JS file that’s been called.

You’ll need to create a new JS file somewhere in your theme files. The file can be blank for now. Take note of where it’s saved; it will be needed in the next step.

Next, add the following function to your theme’s function.php file.

function customizer_dynamic_settings()
{
    wp_enqueue_script( 
        'customizer_dynamic_settings',
        get_template_directory_uri() . '/path/to/new-js-file.js',
        array(
            'jquery',
            'customize-preview'
        )
    );
}

The call to wp_enqueue_script() will load in the JS file that was previously created.

The ‘jquery’ and ‘customize-preview’ array is used to provide these handlers to the script that’s being loaded.

Now, an action can be added to run the customizer_dynamic_settings() function.

add_action( 'customize_controls_enqueue_scripts', 'customizer_dynamic_settings' );

customize_controls_enqueue_scripts is triggered after the customiser is initialised. This will now load the JS script we’ve created every time this script is triggered.

Now this is done, it’s time to start writing the JS to alter the options.

Updating the Customiser

The basic structure for the JS code will look as follows.

wp.customize.bind('ready', function () {
    wp.customize.control('trigger_control', function (control) {
        const responseControl = (value) => {
            // set the response control here
        };
        
        responseControl(control.setting.get());
        control.setting.bind(responseControl);
    });
});

The trigger control is first passed to a function, where the value is read (control.setting.get()).

This value is passed to a function called responseControl, which can be used to set the response control value. The variable value in this function contains the value of the trigger control.

Inside this function, it’s then possible to check this value, and decide how to respond.

responseControl is then bound to the trigger control, which is necessary to make the response function accessible to the control.

This basic structure can be adapted, depending on your needs. The following examples focus on the responseControl function – the rest of the code should remain as is in each example.

Using Checkboxes/Boolean Settings

The most basic example is to use a checkbox to hide/show another setting.

const responseControl = (value) => {
    wp.customize.control('response_control').toggle(value);
};

Here, the response control active state is set based directly on the value of the trigger control.

Using Other Control Types

Rather than using the value directly, you can check the value passed from the trigger control and set the response control accordingly.

For example, WordPress provides an option to hide the site title and tagline from your theme. With these disabled, it makes sense to remove the options to set the title and tagline, as they won’t be used anyway.

The control used by this checkbox is header_textcolor. When unchecked, the value of this setting is blank.

Therefore, checking for blank will give you the state of the checkbox.

const responseControl = (value) => {
    setting = 'blank' !== value;
    wp.customize.control('blogname').toggle(setting);
    wp.customize.control('blogdescription').toggle(setting);
};

This can then be used to set the response control. Note that in this example, two controls are being set. This code will hide the blogname and blogdescription settings when the box to display them is unchecked.

This can be extended to work with any input type – simply check for the value you need, and set your response controls based on the value. A control such as a drop-down menu can provide multiple options, so be sure to check for all values you need to respond to.

Conclusion

Tweaking the options available in the customiser is a great way to streamline your customisation options, ensuring only the relevant options are visible to the user.

Using this basic template, it’s possible to alter controls based on any input.