Since I started to help build the Create theme over at Folsom Creative, I've learned so many new things about the WordPress API. One of those things is how to properly use the WordPress customizer. The customizer is a visual WordPress theme editor with a lot of functionality; the best part is you can easily extend the features of the customizer. There were a lot of changes recently made by the WordPress code team, go check it out here.

The default customizer comes with controls that allow you to edit the site title, colors, widgets, background images, and much more. There might be a point to where you don’t need to add something to the customizer, but it’s possible to make your theme infinitely customizable. This is exactly what we’re doing with Create.

Whether you’re going to build an entire plugin or just add this functionality to your theme it’s probably best to let WordPress know what you are doing. First, create a function where you will be adding the different parts to the customizer. Use this function and use the customize_register hook to add the function you just created.

add_action('customize_register', 'extend_customizer');  
function extend_customizer() {  
    global $wp_customize;
    ...
}

Panels

This is the most recent update to the customizer. Panels allow you to group sections in their proper category. It’s a neat addition and I’m glad they added this, but I would like to see the option for nested panels/sections at some point.

To add a panel you need to use the $wp_customize->add_panel() method.

$wp_customize->add_panel('example_panel', array(
    'title' => 'Example Panel',
    'description' => 'Description',
    'priority' => 10
));

Sections

With sections you can group together controls in a dropdown-like panel. In order to add the section, just use the $wp_customize->add_section() method.

$wp_customize->add_control('example_control', array(
    'label' => 'Example Control',
    'description' => 'Description',
    'settings' => 'example_setting',
    'section' => 'example_section',
    'type' => 'text'
));

Settings

There is really nothing more to settings than setting the id and creating the default value of the option. The type parameter is just to specify what kind of setting it is. You can set option or theme_mod which is the default value. Just use the $wp_customize->add_setting() method.

$wp_customize->add_setting('example_setting', array(
    'default' => 'Default Value',
    'type' => 'theme_mod'
));

Controls

Everything you can change in the customizer is a control. There are very few types of controls that come with WordPress by default, but you can easily extend and create your own. To add a control to the customizer, use the $wp_customize->add_control() method.

$wp_customize->add_control('example_control', array(
    'label'        => 'Example Control',
    'description'  => 'Description',
    'settings'     => 'example_setting',
    'section'      => 'example_section',
    'type'         => 'text'
));

Using The Settings

In order to use the variables that you just created with add_setting in your function. You can use the get_theme_mod(‘example_setting’) or get_option() based on the type of setting it is and grab the value that was set in the customizer. Super easy, just make sure the IDs are spelled correctly when trying to fetch settings.