Listen to this article:
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.
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
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
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.
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!