What is a Customizer API in WordPress?

The Customizer API in WordPress is a framework introduced in version 3.4 that allows users to preview and modify their site in real time. It is accessed under Appearance > Customize within the WordPress admin interface and facilitates adjustments to themes and settings without affecting the live site until changes are saved.

Components of the Customizer API

The Customizer API is structured around four primary types of objects, with the WP_Customize_Manager class orchestrating their management:

Panels: Group together multiple sections for better organization. For example, panels may consolidate all settings related to front-page configurations.
Sections: Serve as containers for controls within the Customizer UI. Sections belong to specific panels when panels are used—for instance, a “Header” panel containing a “Site Identity” section.
Settings: Define individual options saved in the database. They link controls to a corresponding database setting. For example, a site title setting might store custom text entered through the UI.
Controls: Represent the actual user interface elements, such as text fields, checkboxes, sliders, or dropdowns, allowing users to interact with and modify settings.

Using the customize_register Hook

Developers modify the Customizer by hooking into the customize_register action. This enables custom panels, sections, settings, and controls to be defined through the API’s methods, such as add_panel, add_section, add_setting, and add_control.

Below is a basic implementation example:

php
add_action('customize_register', 'my_customize_register');
function my_customize_register($wp_customize) {
    $wp_customize->add_section(
        'example_section',
        array(
            'title' => 'Example Section',
            'priority' => 30
        )
    );
}

The example adds a section labeled “Example Section” and a setting tied to a text control.

Real-Time Preview

Changes made in the Customizer are previewed live through seamless updates in the site preview window. By default, the entire preview reloads to reflect alterations. For better performance, developers can implement postMessage transport and selective refresh.

postMessage updates elements directly in the DOM without requiring page reloads, while selective refresh reloads specific parts of the page dynamically.

Example of applying postMessage for a site title:

php
$wp_customize->add_setting(
    'blogname',
    array(
        'transport' => 'postMessage'
    )
);

A corresponding JavaScript file handles its live previewing.

Security and User Access

The Customizer API uses WordPress’s capability system to control access. By default, options are configured for administrators. Custom capabilities can be defined via the capability argument when registering settings, ensuring granular control over who can use specific features.

For example:

php
$wp_customize->add_setting(
    'example_setting',
    array(
        'capability' => 'edit_theme_options'
    )
);

This restricts the setting to users with the edit_theme_options capability.

Contextual Visibility

The API provides contextual logic based on the previewed front-end state. Widget areas, for instance, are only displayed if visible on the page currently displayed in the Customizer. Developers can define contextual rules to hide or show sections, settings, or controls using the active_callback argument.

For example:

php
$wp_customize->add_setting(
    'example_setting',
    array(
        'type' => 'theme_mod',
        'default' => 'default_value',
        'active_callback' => function () {
            return is_front_page();
        },
    )
);

This ensures the control only appears if the front page is being previewed.

Implementation in Themes

To integrate the Customizer API into themes, developers typically define modifications in the functions.php file. Custom changes made by users through the Customizer are applied on the site using dynamically generated CSS injected into the site’s <head> element.

This preserves the integrity of the original theme files.

For example, enqueueing styles:

php
function theme_customize_css() {
    ?>
    <style type="text/css">
        body {
            background-color: <?php echo get_theme_mod('background_color', '#ffffff'); ?>;
        }
    </style>
    <?php
}
add_action('wp_head', 'theme_customize_css');

This CSS updates dynamically based on user changes without altering the theme files directly.

The WordPress Theme Handbook and the core Customizer API files provide additional guidance and examples for advanced functionality and best practices.