🎛️ Theme Customization API

Why the Customizer?

Before the Customizer, themes shipped their own bespoke "Theme Options" admin pages — every one different, none with a live preview. The Customization API replaced that chaos with a single, consistent interface at Appearance → Customize: controls on the left, a live preview of the actual site on the right.

💡 A useful analogy: The Customizer is a theater lighting booth. You slide the dimmers and swap the gels (controls), and the stage lights up in real time (live preview) — but nothing goes to the paying audience until you hit Publish. Experiment freely; the live site stays untouched until you commit.

Changes preview instantly but only persist when the user clicks Publish.

The Four Building Blocks

Everything in the Customizer is assembled from four object types. Understanding how they nest is the whole game:

Registering Your First Option

All Customizer registration happens inside a function hooked to customize_register, which receives the $wp_customize manager object. Conventionally this lives in inc/customizer.php, pulled in from functions.php.

<?php
// functions.php
require get_template_directory() . '/inc/customizer.php';

A complete option needs three calls: add a section (or reuse one), add a setting, and add a control bound to that setting.

<?php
// inc/customizer.php
function mytheme_customize_register( $wp_customize ) {

    // 1. A section to hold our controls.
    $wp_customize->add_section( 'mytheme_colors', array(
        'title'    => __( 'Theme Colors', 'my-theme' ),
        'priority' => 40,
    ) );

    // 2. A setting: the stored value + how to clean and preview it.
    $wp_customize->add_setting( 'accent_color', array(
        'default'           => '#3b82f6',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'postMessage',
    ) );

    // 3. A control: the UI the user actually sees.
    $wp_customize->add_control(
        new WP_Customize_Color_Control(
            $wp_customize,
            'accent_color',
            array(
                'label'   => __( 'Accent Color', 'my-theme' ),
                'section' => 'mytheme_colors',
            )
        )
    );
}
add_action( 'customize_register', 'mytheme_customize_register' );

For simple controls (text, select, checkbox, number), you can pass a plain array instead of a control object — the object form is only needed for specialized controls like the color picker or image uploader:

<?php
$wp_customize->add_setting( 'body_font', array(
    'default'           => 'system-ui',
    'sanitize_callback' => 'sanitize_text_field',
    'transport'         => 'postMessage',
) );

$wp_customize->add_control( 'body_font', array(
    'type'    => 'select',
    'label'   => __( 'Body Font', 'my-theme' ),
    'section' => 'mytheme_colors',
    'choices' => array(
        'system-ui'   => __( 'System', 'my-theme' ),
        'Georgia'     => __( 'Georgia', 'my-theme' ),
        'Arial'       => __( 'Arial', 'my-theme' ),
    ),
) );

Sanitization: Never Trust Input

Every setting must declare a sanitize_callback. This function runs before the value is saved, guaranteeing that only clean, expected data reaches your database and, later, your page. Skipping it is a security hole — and WordPress theme review will reject the theme.

For values with no built-in sanitizer — a float, a checkbox, or a value from a fixed list — write your own:

<?php
// Checkbox → strict boolean
function mytheme_sanitize_checkbox( $checked ) {
    return ( isset( $checked ) && true === (bool) $checked );
}

// Select → only allow known choices
function mytheme_sanitize_layout( $value, $setting ) {
    $choices = array( 'standard', 'grid', 'masonry' );
    return in_array( $value, $choices, true ) ? $value : $setting->default;
}

// Float
function mytheme_sanitize_float( $value ) {
    return (float) $value;
}

Outputting Settings on the Front End

Saving a setting does nothing visible on its own — you have to read it in your theme with get_theme_mod( $id, $default ) and apply it. The cleanest approach for colors and typography is a small block of inline CSS printed in the head, driven by CSS custom properties.

<?php
function mytheme_customizer_css() {
    $accent = get_theme_mod( 'accent_color', '#3b82f6' );
    $font   = get_theme_mod( 'body_font', 'system-ui' );
    ?>
    <style id="mytheme-customizer">
        :root {
            --accent: <?php echo esc_attr( $accent ); ?>;
        }
        body { font-family: <?php echo esc_attr( $font ); ?>, sans-serif; }
        a, .button { color: var(--accent); }
    </style>
    <?php
}
add_action( 'wp_head', 'mytheme_customizer_css' );

Live Preview with postMessage

Each setting has a transport that decides how the preview updates:

• refresh (the default) — reloads the whole preview iframe on every change. Reliable, but slow and jarring.
• postMessage — sends the change to JavaScript, which updates the preview instantly with no reload. Much nicer, but you must write that JavaScript.

Because our settings above used 'transport' => 'postMessage', we now enqueue a preview script:

<?php
function mytheme_customize_preview_js() {
    wp_enqueue_script(
        'mytheme-customizer-preview',
        get_theme_file_uri( 'assets/js/customizer-preview.js' ),
        array( 'customize-preview' ), // dependency provides the wp.customize API
        wp_get_theme()->get( 'Version' ),
        true
    );
}
add_action( 'customize_preview_init', 'mytheme_customize_preview_js' );

The script listens for each setting and updates the DOM live. With CSS variables, most updates are one line:

// assets/js/customizer-preview.js
( function () {
    // Accent color → update the CSS custom property
    wp.customize( 'accent_color', function ( value ) {
        value.bind( function ( newValue ) {
            document.documentElement.style.setProperty( '--accent', newValue );
        } );
    } );

    // Body font
    wp.customize( 'body_font', function ( value ) {
        value.bind( function ( newValue ) {
            document.body.style.fontFamily = newValue + ', sans-serif';
        } );
    } );
}() );

Selective Refresh & Beyond

Some changes are hard to reproduce accurately in JavaScript — for example, re-rendering a copyright line that mixes markup and dynamic data. Selective refresh is the middle path: it re-renders only the one element that changed via a server callback, giving refresh-level accuracy with near-postMessage speed.

<?php
$wp_customize->add_setting( 'footer_text', array(
    'default'           => '',
    'sanitize_callback' => 'wp_kses_post',
    'transport'         => 'postMessage',
) );

$wp_customize->add_control( 'footer_text', array(
    'type'    => 'textarea',
    'label'   => __( 'Footer Text', 'my-theme' ),
    'section' => 'mytheme_colors',
) );

// Re-render just the .footer-text element when this setting changes.
$wp_customize->selective_refresh->add_partial( 'footer_text', array(
    'selector'        => '.footer-text',
    'render_callback' => function () {
        return wp_kses_post( get_theme_mod( 'footer_text' ) );
    },
) );

Panels for large option sets

Once a theme has many sections, wrap them in a panel so the interface stays tidy:

<?php
$wp_customize->add_panel( 'mytheme_options', array(
    'title'    => __( 'Theme Options', 'my-theme' ),
    'priority' => 30,
) );

// Then assign sections to it:
$wp_customize->add_section( 'mytheme_colors', array(
    'title' => __( 'Colors', 'my-theme' ),
    'panel' => 'mytheme_options',
) );

Conditional controls with active_callback

Show a control only when another setting warrants it — e.g. reveal "Search placeholder" only when header search is enabled:

<?php
$wp_customize->add_control( 'search_placeholder', array(
    'label'           => __( 'Search Placeholder', 'my-theme' ),
    'section'         => 'mytheme_options',
    'type'            => 'text',
    'active_callback' => function () {
        return (bool) get_theme_mod( 'enable_header_search', true );
    },
) );

Hands-on Exercise

<?php
// 1 & 2 — register + control (inside customize_register)
$wp_customize->add_setting( 'link_color', array(
    'default'           => '#2563eb',
    'sanitize_callback' => 'sanitize_hex_color',
    'transport'         => 'postMessage',
) );
$wp_customize->add_control( new WP_Customize_Color_Control(
    $wp_customize, 'link_color',
    array( 'label' => __( 'Link Color', 'my-theme' ), 'section' => 'mytheme_colors' )
) );

<?php
// 3 — output (wp_head)
function mytheme_link_css() {
    $c = get_theme_mod( 'link_color', '#2563eb' );
    echo '<style>:root{--link:' . esc_attr( $c ) . ';} a{color:var(--link);}</style>';
}
add_action( 'wp_head', 'mytheme_link_css' );

// 4 — live preview
wp.customize( 'link_color', function ( value ) {
    value.bind( function ( v ) {
        document.documentElement.style.setProperty( '--link', v );
    } );
} );

Best Practices

Summary & Quiz

📚 Further Reading

• Theme Handbook — The Customize API
• Customizer Objects — Settings, Controls, Sections
• Reference — get_theme_mod()

🚀 What's Next?

You've now taken themes from structure through display to user customization. Next we cross into the other half of extending WordPress: Plugin Development Architecture — where functionality that must outlive any theme belongs.