How to Build a WordPress Gutenberg Inspired Toggle Customizer Control

How to Build a WordPress Gutenberg Inspired Toggle Customizer Control

Listen to this article:

Voiced by Amazon Polly

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 toggle 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.

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 in the following setting and control:

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!

  1. Such a perfect feature! The toggle definitely offers a better experience for features and I could not agree more that it implies much more than a check box or radio. It’s like a button on a car radio. You turn on surround and then you are provided all the settings for sound setup for this feature. Seems like this same approach is needed in the block editor, sidebars the more I get into Gutenberg.

  2. The toggle is perfect for the better experience. Awesome job!
    Rich Tabor, In your code there is two syntax error.

    1) ‘default’ => ‘false’, it should be ‘default’ => false;
    false is Boolean here.

    2) ‘sanitize_callback’ => login_designer_sanitize_checkbox(), it should be ‘sanitize_callback’ => ‘login_designer_sanitize_checkbox’,

  3. Thanks! I had been looking for an Gutenberg inspired toggle and this is perfect! ?

    So I don’t know why but if I include ‘type’ => ‘option’ in add_setting() array I can’t retrieve the get_theme_mod() value, but it works as intended without?

    I noticed recently the design of the toggle in Gutenberg has been changed a little. Any plans on updating to match?

    A little off-topic but thought you might find this useful. Much like your plugin Login Designer I was having to add multiple css selectors to apply custom css to my custom sections. I noticed you can add ‘type’ => ‘class-name’ to the add_section() array which will output .control-section-class-name.

    So in your case you could use the class .control-section-login-designer as a selector for all of your plugins sections instead of multiple id’s to style the css of your controls? I’m not sure if the type value is used for anything else but thought I’d mention as it seems like an easier way of targeting only your custom sections?

Leave a Reply

Your email address will not be published. Required fields are marked *

Up Next:

How to use Amazon Polly and Turn Your Blog Posts into Speech Recordings

How to use Amazon Polly and Turn Your Blog Posts into Speech Recordings