Customizer API

Overview of the WordPress Customizer

The WordPress Customizer provides a user-friendly interface that allows website owners to modify theme settings and preview changes in real time before publishing them. It is designed primarily for non-technical users such as bloggers, designers, and business owners.

The Customizer enables users to adjust theme elements such as:

• Site title and tagline

• Colors and typography

• Header and background images

• Menus and widgets

• Custom theme options

Changes are displayed instantly in the preview window, improving usability and reducing the risk of publishing unintended changes.

From a theme development perspective, it is considered best practice to expose all theme configuration options through the Customizer, ensuring consistency with WordPress standards and improving the overall user experience.

Core Concepts of the Customizer API

The Customizer API is structured around three fundamental components:

Panels

Panels are the top-level containers used to group related sections. They help organize large sets of settings.

Example use cases:

• Theme Options

• Layout Settings

• Typography Settings

Panels are optional but recommended when multiple related sections exist.

Example

function my_theme_customize_panel( $wp_customize ) {

    $wp_customize->add_panel( 'my_theme_options', array(
        'title'       => __( 'Theme Options', 'text-domain' ),
        'description' => __( 'Customize theme settings.', 'text-domain' ),
        'priority'    => 10,
    ) );

}
add_action( 'customize_register', 'my_theme_customize_panel' );

Sections

Sections are containers within panels that group related controls.

Example sections:

• Header Settings

• Footer Settings

• Typography Settings

• Layout Settings

Example

function my_theme_customize_section( $wp_customize ) {

    $wp_customize->add_section( 'header_settings', array(
        'title'    => __( 'Header Settings', 'text-domain' ),
        'panel'    => 'my_theme_options',
        'priority' => 20,
    ) );

}
add_action( 'customize_register', 'my_theme_customize_section' );

Settings

Settings represent the data that will be stored in the database. They define what value the user is modifying.

WordPress supports two main setting types:

Important arguments for settings include:

• default

• sanitize_callback

• transport

Example

$wp_customize->add_setting( 'header_text_color', array(
    'default'           => '#333333',
    'sanitize_callback' => 'sanitize_hex_color',
    'transport'         => 'postMessage'
) );

Controls

Controls define the user interface element used to modify a setting.

Common control types include:

• Text input

• Checkbox

• Radio button

• Select dropdown

• Color picker

• Image upload

• File upload

Each control is connected to a setting.

Example

$wp_customize->add_control( 'header_text_color', array(
    'label'   => __( 'Header Text Color', 'text-domain' ),
    'section' => 'header_settings',
    'type'    => 'text',
) );

The customize_register Hook

The customize_register action hook is used to register panels, sections, settings, and controls with the Customizer.

This hook provides access to the $wp_customize object, an instance of WP_Customize_Manager.

Example

function my_theme_customize_register( $wp_customize ) {

    // Add section
    $wp_customize->add_section( 'my_theme_section', array(
        'title'    => __( 'My Theme Settings', 'text-domain' ),
        'priority' => 160,
    ) );

}
add_action( 'customize_register', 'my_theme_customize_register' );

Adding a Color Picker Control

WordPress provides built-in control classes such as WP_Customize_Color_Control.

Example Implementation

function my_theme_customize_register( $wp_customize ) {

    // Section
    $wp_customize->add_section( 'my_theme_section', array(
        'title' => __( 'My Theme Settings', 'text-domain' ),
    ) );

    // Setting
    $wp_customize->add_setting( 'header_text_color', array(
        'default'           => '#333',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'postMessage',
    ) );

    // Control
    $wp_customize->add_control(
        new WP_Customize_Color_Control(
            $wp_customize,
            'header_text_color',
            array(
                'label'   => __( 'Header Text Color', 'text-domain' ),
                'section' => 'my_theme_section',
            )
        )
    );

}
add_action( 'customize_register', 'my_theme_customize_register' );

Outputting Customizer Settings in the Theme

Theme developers must retrieve Customizer values and apply them within the theme.

For theme modifications, use:

get_theme_mod()

Example

function my_theme_customize_css() {
?>

<style>
header h1 {
    color: <?php echo esc_html( get_theme_mod( 'header_text_color', '#333' ) ); ?>;
}
</style>

<?php
}
add_action( 'wp_head', 'my_theme_customize_css' );

This dynamically applies the user-selected color to the site header.

Live Preview with postMessage

The transport argument controls how preview updates occur.

Example:

'transport' => 'postMessage'

To enable this feature, JavaScript must listen for Customizer changes.

Example JavaScript

wp.customize('header_text_color', function(value) {
    value.bind(function(newval) {
        document.querySelector('header h1').style.color = newval;
    });
});

Adding Custom JavaScript for Live Preview

Custom preview scripts must be enqueued during the Customizer preview.

function my_theme_customize_preview_js() {

    wp_enqueue_script(
        'my-theme-customizer',
        get_template_directory_uri() . '/js/customizer.js',
        array( 'customize-preview' ),
        null,
        true
    );

}
add_action( 'customize_preview_init', 'my_theme_customize_preview_js' );

Custom Controls

Developers can create custom control classes to build advanced UI components.

Examples include:

• Toggle switches

• Range sliders

• Typography selectors

• Icon pickers

Basic Custom Control Example

class My_Custom_Control extends WP_Customize_Control {

    public function render_content() {
        ?>
        <label>
            <span><?php echo esc_html( $this->label ); ?></span>
            <input type="text" <?php $this->link(); ?> value="<?php echo esc_attr( $this->value() ); ?>">
        </label>
        <?php
    }

}

Usage:

$wp_customize->add_control(
    new My_Custom_Control(
        $wp_customize,
        'custom_text',
        array(
            'label'   => 'Custom Text',
            'section' => 'my_theme_section',
        )
    )
);

Common Use Cases of the Customizer API

The Customizer API is commonly used to provide theme configuration options such as:

Layout Settings

• Sidebar position

• Container width

• Grid layout

Branding Options

• Logo upload

• Header image

• Brand colors

Typography Controls

• Font family

• Font size

• Line height

Blog Settings

• Excerpt length

• Featured image toggle

• Post metadata display

Footer Settings

• Footer text

• Widget areas

• Social media links

Built-in Core Sections in the Customizer

WordPress provides several default sections including:

• Site Identity

• Colors

• Header Image

• Background Image

• Menus

• Widgets

• Homepage Settings

• Additional CSS

Developers can extend these sections or create new ones depending on theme requirements.

Best Practices for Using the Customizer API

Use meaningful setting IDs
Always sanitize user input using sanitize_callback
Group related controls within sections and panels
Use postMessage for better user experience where possible
Provide sensible default values
Ensure accessibility and clear labels for controls

Key Functions and Methods