WordPress Theme Customizer

Read This First

The best tutorial I have found for understanding the Customizer API quickly is Narayan Prusty’s Getting Started with the WordPress Customization API (SitePoint, Feb. 2015). It only covers some basic concepts, but I found it to be extremely useful in wrapping my head around some concepts that were causing me to get lost in deeper articles.


[Each of these terms is used in the context of the Customizer, thus when reading “The Admin UI” it should be read contextually as “The [Customizer] Admin API.” This reduces redundancy, but if not taken note of here could cause confusion with other areas of WordPress outside the current context (e.g. the general UI).]

  • Customizer – The Admin  UI, but used generally to refer to the entire Customizer interface and underlying API.
    • Options can be granted on a granular basis and contextual to what the user is previewing.
  • Theme Modification API – CRUD.
  • Theme Customization API – Add/Remove settings.
  • The Customizer API is object-oriented, the main types of objects are:
    • Panels – In the UI, top-level, contains sections, for organization.
    • Sections – In the UI, contains settings, for organization.
    • Settings – The back-end interface that handles connecting Controls to the db.
    • Controls – UI interface for settings, allows users to interact with settings via intuitive UI.
  • Theme Options – There have been, historically, a number of different ways to build theme options – but the official (canonical) way is now to use the Customizer API.


Each object is represented by a PHP class and all objects are managed by the Customize Manager object (WP_Customize_Manager), oftentimes instantiated as $wp_customize.

  • The Customize Manager provides add_, get_, and remove_ methods for each Customizer object type (e.g. panels, sections, settings, controls).

Control Objects

There is a base WP_Customize_Control object, custom controls are essentially subclasses of the this base object. Several are built-in: color, upload, image, background image, header image.

Base Object / Class

This is the most generic object.

Color Picker Control


Further Reading

Media Control (Select / Upload Files)


Upload File Control


This appears to be for general file control.


Image Control


Stores the URL of the image, use media control for image id.


Live Preview / Save / Sanitization

Settings are responsible for live-preview, saving, and sanitization of Customizer objects.

Primary Types of Settings

Settings can be saved primarily in two places.

One is as an option in the wp_options table. These are applied regardless of the active theme, thus themes should not add options.

Why do they exist? Because they can be appropriate when writing plugins.

The other is as a theme modification (theme_mods) and these are only active when the theme that created them is active.

Retrieving Theme Mods / Options

One uses get_theme_mod() and/or get_option() when retrieving a setting set in customizer.

The second value should be the default value of the field being pulled.


A control is the UI that is used by a user to select the value they desire to be saved for a specific setting.

The most important parameter is type, because this determines the type of UI that will be displayed.

WP includes a number of built-in types: text, checkbox, textarea, radio, select, dropdown-pages.


Core Section Priorities:

  • 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


  • “More than just grouping sections of controls, panels are designed to provide distinct contexts for the Customizer, such as Customizing Widgets, Menus, browsing themes, or perhaps in the future, editing posts.”
  • Usually not necessary to utilize Panels, Sections are oftentimes sufficient.

Using AJAX for Faster Live Previews

Live Previews are handled automatically by Customizer but involve a complete page reload. Using JavaScript it is possible to reload only the necessary portion of the page.

To utilize AJAX you need to set the transport method for a setting to postMessage.

Bibliography / Further Reading

On Custom Controls