The WordPress Customizer API

Adding a Panel

// Add a panel for all theme options
$wp_customize->add_panel(
    'mytheme_options',
    array(
        'title'       => __( 'Theme Options', 'mytheme' ),
        'description' => __( 'All theme customization options', 'mytheme' ),
        'priority'    => 30,
    )
);

// Add sections to the panel
$wp_customize->add_section(
    'mytheme_colors',
    array(
        'title'       => __( 'Theme Colors', 'mytheme' ),
        'description' => __( 'Customize the colors of your theme', 'mytheme' ),
        'panel'       => 'mytheme_options', // This is the key part that adds the section to the panel
        'priority'    => 10,
    )
);

$wp_customize->add_section(
    'mytheme_typography',
    array(
        'title'       => __( 'Typography', 'mytheme' ),
        'description' => __( 'Customize the fonts and typography', 'mytheme' ),
        'panel'       => 'mytheme_options',
        'priority'    => 20,
    )
);

Using Built-in Custom Controls

// Add an image upload control
$wp_customize->add_setting(
    'header_image',
    array(
        'default'           => '',
        'sanitize_callback' => 'esc_url_raw',
    )
);

$wp_customize->add_control(
    new WP_Customize_Image_Control(
        $wp_customize,
        'header_image',
        array(
            'label'    => __( 'Header Image', 'mytheme' ),
            'section'  => 'mytheme_header',
            'settings' => 'header_image',
        )
    )
);

// Add a cropped image control
$wp_customize->add_setting(
    'site_logo',
    array(
        'default'           => '',
        'sanitize_callback' => 'esc_url_raw',
    )
);

$wp_customize->add_control(
    new WP_Customize_Cropped_Image_Control(
        $wp_customize,
        'site_logo',
        array(
            'label'         => __( 'Site Logo', 'mytheme' ),
            'section'       => 'title_tagline',
            'settings'      => 'site_logo',
            'width'         => 300,
            'height'        => 100,
            'flex_width'    => true,
            'flex_height'   => true,
        )
    )
);

// Add a media control
$wp_customize->add_setting(
    'background_video',
    array(
        'default'           => '',
        'sanitize_callback' => 'absint',
    )
);

$wp_customize->add_control(
    new WP_Customize_Media_Control(
        $wp_customize,
        'background_video',
        array(
            'label'     => __( 'Background Video', 'mytheme' ),
            'section'   => 'mytheme_header',
            'settings'  => 'background_video',
            'mime_type' => 'video',
        )
    )
);

Creating a Custom Range Control

/**
 * Custom Range Control class.
 */
class Mytheme_Customize_Range_Control extends WP_Customize_Control {
    /**
     * Control type.
     *
     * @var string
     */
    public $type = 'range';
    
    /**
     * Minimum value.
     *
     * @var int
     */
    public $min = 0;
    
    /**
     * Maximum value.
     *
     * @var int
     */
    public $max = 100;
    
    /**
     * Step value.
     *
     * @var int
     */
    public $step = 1;
    
    /**
     * Render control content.
     */
    public function render_content() {
        ?>
        <label>
            <?php if ( ! empty( $this->label ) ) : ?>
                <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
            <?php endif; ?>
            
            <?php if ( ! empty( $this->description ) ) : ?>
                <span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
            <?php endif; ?>
            
            <div class="range-slider">
                <input type="range" <?php $this->input_attrs(); ?> value="<?php echo esc_attr( $this->value() ); ?>" <?php $this->link(); ?> min="<?php echo esc_attr( $this->min ); ?>" max="<?php echo esc_attr( $this->max ); ?>" step="<?php echo esc_attr( $this->step ); ?>" />
                <span class="range-value"><?php echo esc_attr( $this->value() ); ?></span>
            </div>
        
        
        
        add_setting(
    'content_width',
    array(
        'default'           => '1200',
        'sanitize_callback' => 'absint',
        'transport'         => 'postMessage',
    )
);

$wp_customize->add_control(
    new Mytheme_Customize_Range_Control(
        $wp_customize,
        'content_width',
        array(
            'label'       => __( 'Content Width (px)', 'mytheme' ),
            'section'     => 'mytheme_layout',
            'settings'    => 'content_width',
            'min'         => 800,
            'max'         => 1600,
            'step'        => 10,
        )
    )
);

Adding Selective Refresh Support

// Add selective refresh support for the site title
$wp_customize->selective_refresh->add_partial(
    'blogname',
    array(
        'selector'        => '.site-title',
        'render_callback' => function() {
            return get_bloginfo( 'name' );
        },
    )
);

// Add selective refresh support for a custom setting
$wp_customize->add_setting(
    'footer_text',
    array(
        'default'           => 'Copyright © ' . date('Y') . ' ' . get_bloginfo( 'name' ),
        'sanitize_callback' => 'wp_kses_post',
        'transport'         => 'postMessage',
    )
);

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

$wp_customize->selective_refresh->add_partial(
    'footer_text',
    array(
        'selector'        => '.site-footer .footer-text',
        'render_callback' => function() {
            return get_theme_mod( 'footer_text' );
        },
    )
);

Using Active Callbacks

// Add a setting for enabling a feature
$wp_customize->add_setting(
    'enable_header_search',
    array(
        'default'           => true,
        'sanitize_callback' => 'mytheme_sanitize_checkbox',
    )
);

$wp_customize->add_control(
    'enable_header_search',
    array(
        'label'    => __( 'Enable Header Search', 'mytheme' ),
        'section'  => 'mytheme_header',
        'type'     => 'checkbox',
    )
);

// Add settings that are only relevant if header search is enabled
$wp_customize->add_setting(
    'search_placeholder',
    array(
        'default'           => __( 'Search...', 'mytheme' ),
        'sanitize_callback' => 'sanitize_text_field',
    )
);

$wp_customize->add_control(
    'search_placeholder',
    array(
        'label'           => __( 'Search Placeholder Text', 'mytheme' ),
        'section'         => 'mytheme_header',
        'type'            => 'text',
        'active_callback' => 'mytheme_is_header_search_enabled',
    )
);

// Callback function to check if header search is enabled
function mytheme_is_header_search_enabled() {
    return get_theme_mod( 'enable_header_search', true );
}

// Sanitize checkbox function
function mytheme_sanitize_checkbox( $checked ) {
    return ( ( isset( $checked ) && true == $checked ) ? true : false );
}

// Add a section for header options
$wp_customize->add_section(
    'mytheme_header',
    array(
        'title'       => __( 'Header Options', 'mytheme' ),
        'description' => __( 'Customize your site header', 'mytheme' ),
        'panel'       => 'mytheme_options',
        'priority'    => 30,
    )
);

// Header Layout
$wp_customize->add_setting(
    'header_layout',
    array(
        'default'           => 'standard',
        'sanitize_callback' => 'mytheme_sanitize_select',
        'transport'         => 'postMessage',
    )
);

$wp_customize->add_control(
    'header_layout',
    array(
        'label'    => __( 'Header Layout', 'mytheme' ),
        'section'  => 'mytheme_header',
        'type'     => 'select',
        'choices'  => array(
            'standard'      => __( 'Standard (Logo + Menu)', 'mytheme' ),
            'centered'      => __( 'Centered (Logo above Menu)', 'mytheme' ),
            'split'         => __( 'Split (Menu - Logo - Menu)', 'mytheme' ),
            'transparent'   => __( 'Transparent Overlay', 'mytheme' ),
        ),
    )
);

// Sticky Header
$wp_customize->add_setting(
    'sticky_header',
    array(
        'default'           => false,
        'sanitize_callback' => 'mytheme_sanitize_checkbox',
        'transport'         => 'postMessage',
    )
);

$wp_customize->add_control(
    'sticky_header',
    array(
        'label'    => __( 'Enable Sticky Header', 'mytheme' ),
        'section'  => 'mytheme_header',
        'type'     => 'checkbox',
    )
);

// Header Background Color
$wp_customize->add_setting(
    'header_background',
    array(
        'default'           => '#ffffff',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'postMessage',
    )
);

$wp_customize->add_control(
    new WP_Customize_Color_Control(
        $wp_customize,
        'header_background',
        array(
            'label'    => __( 'Header Background Color', 'mytheme' ),
            'section'  => 'mytheme_header',
            'settings' => 'header_background',
        )
    )
);

// Header Text Color
$wp_customize->add_setting(
    'header_text_color',
    array(
        'default'           => '#000000',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'postMessage',
    )
);

$wp_customize->add_control(
    new WP_Customize_Color_Control(
        $wp_customize,
        'header_text_color',
        array(
            'label'    => __( 'Header Text Color', 'mytheme' ),
            'section'  => 'mytheme_header',
            'settings' => 'header_text_color',
        )
    )
);

// Header Padding
$wp_customize->add_setting(
    'header_padding',
    array(
        'default'           => '20',
        'sanitize_callback' => 'absint',
        'transport'         => 'postMessage',
    )
);

$wp_customize->add_control(
    'header_padding',
    array(
        'label'       => __( 'Header Padding (px)', 'mytheme' ),
        'section'     => 'mytheme_header',
        'type'        => 'number',
        'input_attrs' => array(
            'min'  => 0,
            'max'  => 50,
            'step' => 1,
        ),
    )
);

// JavaScript for live preview
function mytheme_header_customizer_js() {
    ?>