Creating panels, sections, and controls with the Customize JS API

Until now I mostly used the PHP API of the customizer. Since Weston Ruter’s post about the improvements of the Customize JS API in WordPress 4.9, I wanted to change that and learn more about the Customize JS API. This post shows you how to create panels, sections, and controls with that API.

Why the Customize JS API has advantages against the PHP API

I did not think about that much – I began with the PHP API and stayed with it. But the PHP API is – like Weston writes in his post – just a wrapper for the JS API. He also writes:

»The point here is that in order for the Customizer to scale, the JavaScript API must be used directly. So this is why the Customizer JS API improvements in 4.9 are important as they fix many longstanding annoyances and shortcomings with the JS API.«

Weston Ruter in Improvements to the Customize JS API in 4.9

Weston Ruter in Improvements to the Customize JS API in 4.9

So I thought to myself, I will try it out at the next opportunity. And because my Hannover and Bornholm themes need a visual and technical update, I already had it.

Disadvantage of the Customize JS API

There is also a disadvantage of the Customize JS API: currently, it is not very well documented, so it takes some time to find information, even if the API is entirely written in one (or just some) core files, so theoretically one could extract its functioning from there. For me, that was just a little help.

More helpful was Google, and frequently appearing answers and posts from Weston Ruter 🙂

But now let us come to the main topic of this post:

Creating panels, sections, and controls with the JS API

At first, we need to enqueue a JS file into the customizer’s control area. For that we use the following code:

// Include scripts into the customizer.
add_action( 'customize_controls_enqueue_scripts', 'hannover_customizer_controls_script' );

/**
 * Prints styles inside the customizer view.
 */
function hannover_customizer_controls_script() {
	// Add script control section.
	wp_enqueue_script( 'hannover-customize-controls', get_theme_file_uri( 'assets/js/customize-controls.js' ), [], null, true );
}
Code language: JavaScript (javascript)

Now we create the customize-controls.js in the assets/js folder with the following content:

/**
 * Custom JavaScript functions for the customizer controls.
 *
 * @version 2.0.0
 *
 * @package Hannover
 */
;(function (api) {
	api.bind('ready', function () {
		// Create theme options panel.
		api.panel.add(
			new api.Panel('hannover_theme_options', {
				title: 'Theme Options',
			})
		);

		// Add section.
		api.section.add(
			new api.Section('hannover_example_section', {
				title: 'Example Section',
				panel: 'hannover_theme_options',
				customizeAction: 'Customizing ▸ Theme Options'
			})
		);

		// Add checkbox control.
		api.control.add(
			new api.Control('hannover_example_control', {
				setting: 'hannover_example_setting',
				type: 'checkbox',
				section: 'hannover_example_section',
				label: 'Check this box to do something.'
			})
		);
	});
})(wp.customize);
Code language: PHP (php)

We wait until the Customizer is ready and add a panel, section, and control. You can see that the code for adding each of the elements is quite similar. The first parameter of the new call is the ID, after that, there comes an object with the options, like known from the PHP API.

One exception from that: customizeAction for new api.Section defines the string that is shown above the title in the section view:

And with that, we are at the end of this small introduction to the Customize JS API. Important is, that – generally – you define the settings with the PHP API – otherwise, the values are not stored in the database. There is a way to create settings via the JS API dynamically, but that is the topic of another article.