23rd May 2016 in Cheat Sheet, Wordpress

WordPress Theme Customizer API – Cheatsheet

Theme Customizer API allows WordPress theme developers to create customization options for themes. Biggest benefit of using this API is that it allow theme users to preview any changes before publishing them on the live site.

Note: You can use a graphical interface to generate code for Theme Customizer API, by using the WP Theme Customizer Builder.

You can add code for Theme Customizer API directly in functions.php file, but I recommend that you should create a separate file named customizer.php and include it in functions.php.

Include customizer.php in functions.php

require get_template_directory() . '/customizer.php';

The first step is to register your customizer; you can add all the code to create sections, settings, controls, etc. inside this function.

Register your customizer

function mytheme_customize_register( $wp_customize ) {
//All our sections, settings, and controls will be added here
add_action( 'customize_register', 'mytheme_customize_register' );


(introduced in WordPress 4.0)
Panels are containers for sections, allowing multiple sections to be grouped together.

add panel (https://developer.wordpress.org/reference/classes/wp_customize_manager/add_panel/)

$wp_customize->add_panel( 'panel_id', array(
  'title' => __( 'Menus', 'theme_textdomain' ),
  'description' => $description, // Include html tags such as <p>
  'priority' => 160, // Mixed with top-level-section hierarchy. 
) );

You can use get_panel() or remove_panel() by passing panel ID to it


Panels must contain at least one Section, which must contain at least one Control, to be displayed.


Sections are UI containers for controls, to improve their organization.

add section (https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_section)

$wp_customize->add_section( 'section_id', array(
  'title' => __( 'Custom CSS', 'theme_textdomain' ),
  'description' => __( 'Add custom CSS here', 'theme_textdomain' ),
  'panel' => '', // Not typically needed.
  'priority' => 160,
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
) );

You only need to include fields that you want to override the default values of.

You can use get_section() or remove_section() by passing section ID to it.


WordPress does include a few built-in sections. If you want to use any of the existing, built-in ones, you don’t need to declare them with add_section(). Instead, refer to them by name. The following sections are built-in:

Title ID Priority (Order)
Site Title & Tagline title_tagline 20
Colors colors 40
Header Image header_image 60
Background Image background_image 80
Navigation nav 100
Widgets (Panel) widgets 110
Static Front Page static_front_page 120
default 160


Settings associate UI elements (controls) with settings that are saved in the database. Settings handle live-previewing, saving, and sanitization of your controls.

add setting (https://codex.wordpress.org/Class_Reference%5CWP_Customize_Manager%5Cadd_setting)

$wp_customize->add_setting( 'setting_id', array(
  'type' => 'theme_mod', // or 'option'
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
  'default' => '',
  'transport' => 'refresh', // or postMessage
  'sanitize_callback' => '',
  'sanitize_js_callback' => '', // Basically to_json.
) );

Important: Do not use a setting ID that looks like widget_*, sidebars_widgets[*], nav_menu[*], or nav_menu_item[*]. These setting ID patterns are reserved for widget instances, sidebars, nav menus, and nav menu items respectively. If you need to use “widget” in your setting ID, use it as a suffix instead of a prefix, for example “homepage_widget”.

You can use get_setting() or remove_setting() by passing setting ID to it.



Controls are the primary Customizer object for creating UI. Specifically, every control must be associated with a setting, and that setting will save user-entered data from the control to the database (in addition to displaying it in the live-preview and sanitizing it).

add control (https://codex.wordpress.org/Class_Reference%5CWP_Customize_Manager%5Cadd_control)

$wp_customize->add_control( 'setting_id', array(
  'type' => 'date',
  'priority' => 10, // Within the section.
  'section' => 'colors', // Required, core or custom.
  'label' => __( 'Date', 'theme_textdomain' ),
  'description' => __( 'This is a date control with a red border.', 'theme_textdomain' ),
  'input_attrs' => array(
    'class' => 'my-custom-class-for-js',
    'style' => 'border: 1px solid #900',
    'placeholder' => __( 'mm/dd/yyyy', 'theme_textdomain' ),
  'active_callback' => 'is_front_page',
) );
$wp_customize->add_control( 'your_setting_id', array(
    'label'      => __( 'Dark or light theme version?', 'theme_textdomain' ),
    'section'    => 'your_section_id',
    'settings'   => 'your_setting_id',
    'type'       => 'radio',
    'choices'    => array(
        'dark'   => __( 'Dark', 'theme_textdomain' ),
        'light'  => __( 'Light', 'theme_textdomain' )

The most important parameter when adding a control is its type. It determines what type of UI the Customizer displays. Core provides several built-in control types:

  • checkbox
  • textarea
  • radio (pass a keyed array of values => labels to the choices argument)
  • select (pass a keyed array of values => labels to the choices argument)
  • dropdown-pages
  • For any input type supported by the html element, simply pass the type attribute value to the type parameter when adding the control. This allows support for control types such as text, hidden, number, range, url, tel, email, search, time, date, datetime, and week.

Core Custom Controls

  • background image
  • color
  • header image
  • media (By specifying the mime_type parameter when adding the control, you can instruct the media library show to a specific type such as an images or audio)

Code for color control

    new WP_Customize_Color_Control( $wp_customize, 'link_color', 
        'label'      => __( 'Header Color', 'theme_textdomain' ),
        'section'    => 'your_section_id',
        'settings'   => 'your_setting_id',
) ) );

Code for media control

    new WP_Customize_Media_Control( $wp_customize, 'image_control', 
        'label' => __( 'Featured Home Page Image', 'theme_textdomain' ),
        'section' => 'media',
        'mime_type' => 'image',
) ) );

You can use get_control() or remove_control() by passing ID to it.


Retrieve values to display in your theme

You need to use your setting ID to retrieve value of a setting.

There are two primary types of settings – options and theme modifications. Options are stored directly in the wp_options table of the WordPress database and apply to the site regardless of the active theme. Option type settings are rarely used with themes, they are usually used with plugins. Theme mods, on the other hand, are specific to a particular theme. Most theme options should be theme_mods.

<?php echo get_theme_mod( 'background_color' ); ?>;


<?php echo get_option( 'blogname' ); ?>

I know that every aspect of Theme Customizer API is not covered in this cheetsheet. I will improve this over the time.

You can suggest any additions / modifications that you feel are missing in this cheatsheet, in the comments below.

About the author

Alok Jain

Alok design digital experiences to help businesses achieve their goals. He is passionate about designing right User Experience for their customers. For over 15 years, he have worked with small startups to mature product teams. Whether it is designing a WordPress product, a frontend experience, WooCommerce, Shopify, he follow the best product development practices for design and code, for desktop or mobile.