How to Build a WordPress Gutenberg Inspired Toggle Customizer Control

If you know me, you know I’m a stickler for building beautiful and highly intuitive user experiences. I’m always looking to make my own WordPress themes simpler and easier to use.

After spending quite a bit of time within the Gutenberg editor, I thought the editor’s toggle controls would be a great addition within the context of the WordPress Customize API. So I developed a Customizer control inspired by Gutenberg’s inspector region for my WordPress themes.

Here’s a quick guide on how I built the toggle control and how to add it to your theme’s WordPress Customizer. Let’s get started!

A case for the toggle switch

Toggles are deployed within an interface to represent an action, such as turning something on or off. A common analogy is a simple light switch, where one direction turns on a light, while the other turns it off.

A Toggle Customizer Control within Login Designer.

The visual cue of a toggle is quite different than a checkbox, even if the markup is relatively similar. A toggle switch implies instance, whereas a checkmark implies selection. This means users expect a more immediate change when manipulating a toggle than a checkbox.

That saying, if you are not already leveraging live previewing within the Customizer, you’re really missing out on providing a first-class customizing experience for your users. There’s really no excuse — plus, it’s not difficult.

Extending WP_Customize_Control

Custom controls are subclasses of the base WP_Customizer_Control object that allow any html markup and functionality that you might need. In order to add our toggle WordPress Customizer control, you’ll need to create a new class and extend it using WP_Customizer_Control.

Here’s the class:

Above, you’ll see the two methods within our custom control: the WP_Customizer_Control::enqueue() method, which is used to enqueue control related scripts and styles, and the WP_Customizer_Control::render_content() method, which is used to define the control’s content and toggle markup.

Adding the class to your theme

To add, remove, or modify any Customizer object (such as our toggle Customizer control) we’ll need to use the customize_register hook. If your WordPress theme is already using the Theme Customize API, navigate to your instance of the WP_Customize_Manager object (customize_register) and add the snippet in the "Adding the Customizer toggle control" section below, pointing to the class within your theme’s directory.

You’ll also want to ensure that the toggle’s wp_enqueue_style() style and javascript files properly resolve within your WordPress theme’s directory.

You’ll need to download the styles and scripts (GitHub links) to add.


The add_setting() method of the WP_Customizer object accepts a sanitize_callback argument, which is used to specify a sanitization callback. The following sanitization function accepts the input data and returns the sanitized data.

Adding the Customizer toggle control

Now that the control has been added to your WordPress theme, let’s add your first toggle control to the Customizer. Once again, navigate to your WP_Customize_Manager object and paste the setting and control from the customizer.php gist up above.

If you’ve updated the Login_Designer_Toggle_Control prefix within the class file, you’ll need to update the control here with your prefix. Next, ensure the control’s section is properly set, then refresh the Customizer preview.

A Toggle Customizer Control within Login Designer.
A Toggle Customizer Control within Login Designer.

Awesome! You’ve just added your first custom WordPress Customizer toggle control. In a future article I’ll cover how to show/hide other options based on the status of a toggle (or any other option). That’s really neat too.


Remember, when building out Customizer settings, it’s important to focus on using consistent and predictable UI elements. If you deploy a toggle switch on, you should implement toggles throughout all other relative options.

And if you’ve decided to deploy toggle switches in lieu of checkboxes, go the extra mile and add live previewing to those controls. The WordPress Customizer doesn’t have to feel clunky — it can be absolutely beautiful and empowering.

Note: The plugin featured is my Login Designer, the revolutionary login page customizer for WordPress. Take it for it a spin!