How to customize the WordPress theme customizer defaults

The theme customizer feature was introduced in WordPress 3.4, released June 2012. Since then, it’s been a great tool that’s allowed theme developers to move away from complex options managers to a simpler, more logical interface where many settings can even be live previewed.

Over the last couple of years, there have been a few really great resources written for utilizing the theme customizer and extending it. There are a few I think you should read if you are getting serious about the customizer.

Resources for working with the theme customizer

• Theme customization API on the Codex
• Samuel “Otto” Wood on the customizer: Parts One (basic utilization), Two (dumping options pages), and Three (custom controls)
• Theme customizer default sections, by Devin Price (very handy for the later items I’ll cover in this article)
• WordPress theme customizer: A comprehensive guide by Alex Mansfield. An excellent and thorough overview of the customizer and how to use it
• A guide to the WordPress theme customizer: 8 party series by Tom McFarlin on Wptuts+
• Theme customizer custom controls: A solid set of common custom controls by Paul Underwood

So I guess that’s some pretty serious homework. But if you are planning to utilize the customizer in your client or theme work, it’s great learning to see how these various folks are handling it. Some of the implementations I linked vary from one another, but you should pick up on patterns and see which aspects of each method you like for your own coding style.

Before we go further, let’s cover a couple more notes on the customizer.

The default WordPress customizer settings

You should know from reading the above posts that creating new items for the customizer is broken down by defining sections, settings, and controls. You will also notice that core defines some default sections based on your theme adding support for features, like custom headers and backgrounds. The default sections are: title_tagline, colors, header_image, background_image, nav, and static_front_page.

When I was playing with the customizer for a project recently, I felt like some customizer sections and settings didn’t really fit the order and language I wanted them to have. So I went looking for how to customize such things to my liking. It’s actually quite simple.

The $wp_customize object is the most important part about working in the customizer screen. When we hook into customize_register to add sections, settings, and controls, we are adding to the default customizer settings $wp_customize has at that time. Therefore, it’s also an appropriate time to change the default settings.

If you spend time in the WP_Customize_Manager class in core, you’ll notice that just as there are methods for add_section(), add_setting(), and add_control(), there are also methods for “getting” and “removing” sections, settings, and controls. So you can see it in real life, here is the core code within the WP_Customize_Manager class for adding, getting, and removing sections.

/**
 * Add a customize section.
 *
 * @since 3.4.0
 *
 * @param string $id A specific ID of the section.
 * @param array $args Section arguments.
 */
public function add_section( $id, $args = array() ) {
	if ( is_a( $id, 'WP_Customize_Section' ) )
		$section = $id;
	else
		$section = new WP_Customize_Section( $this, $id, $args );

	$this->sections[ $section->id ] = $section;
}

/**
 * Retrieve a customize section.
 *
 * @since 3.4.0
 *
 * @param string $id A specific ID of the section.
 * @return object The section object.
 */
public function get_section( $id ) {
	if ( isset( $this->sections[ $id ] ) )
		return $this->sections[ $id ];
}

/**
 * Remove a customize section.
 *
 * @since 3.4.0
 *
 * @param string $id A specific ID of the section.
 */
public function remove_section( $id ) {
	unset( $this->sections[ $id ] );
}

Not so scary, right? So, just as we are able to add sections, settings, and controls to the defaults, we should also be able to alter and even remove them.

Alter default customizer settings

In fact, the Codex and most themes already utilize these methods in some code you’ve seen. For example, here’s a single line of code that changes the transport property of the blogname setting, which allows the live preview to change instantly as the user types a new blog name.

$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';

You see it now, right? We are changing the transport parameter of the blogname setting within the main $wp_customize object to the value postMessage. It’s pretty standard PHP here, but admittedly can be a bit intimidating to those of us that learned backwards (WordPress first).

Just like we alter the transport property above within the get_setting() method, we can also change other properties. In my case, I wanted to change some of the labels, move a few settings to different sections, and reorder a priority or two. Here are samples of that code:

$wp_customize->get_setting( 'blogname'          )->transport = 'postMessage';
$wp_customize->get_setting( 'blogdescription'   )->transport = 'postMessage';
$wp_customize->get_setting( 'header_textcolor'  )->transport = 'postMessage';
$wp_customize->get_control( 'background_color'  )->section   = 'background_image';
$wp_customize->get_section( 'background_image'  )->title     = 'Background Settings';
$wp_customize->get_section( 'title_tagline'     )->title     = 'Site Title / Logo';
$wp_customize->get_section( 'static_front_page' )->title     = 'Home Page Settings';
$wp_customize->get_section( 'static_front_page' )->priority  = 29;

You can see that the first three are just changing the default transport property to allow live previewing. The next moves the background_color control to the background_image section, instead of keeping it in colors. I did this because I created a separate section for my theme’s appearance and didn’t want a distinct section for color customization. I also changed a couple of section titles as well as a section priority.

Now, if I want I can continue the example by removing the colors section entirely, since I won’t need it.

$wp_customize->remove_section( 'colors' );

However, in this example, it’s not particularly relevent, since only background color is in the section by default; and since I moved it, the colors section won’t show up at all. But if you want to prevent anything else from potentially bringing this section back (or any other) in any way, that line of code with your section of choice input will do it.

Similarly, just as you can remove a section, you could also remove a single control. If you don’t have a need for the blog description, for instance, you can remove it like so:

$wp_customize->remove_control( 'blogdescription' );

Since add_setting() simply registers its existence and add_control() is what renders it, that’s why it makes sense to use remove_control() instead of remove_setting() to get rid of it. Of course you could remove both if you’re just in the mood.

Wrapping things up

By the end of my experiment, I was able to adjust my theme’s default customizer settings to better fit my custom sections and settings I had built. This allowed me to craft a more cohesive overall customization experience for the theme.

I hope you are able to learn from the great resources I linked, just as I did. And I hope you also aren’t afraid to mix up the default settings a bit now to make your users’ theme customizer just a tad bit more awesome.