Theme Development

Digging Into the Theme Customizer: Components


In the first part of this series, I introduced the Theme Customizer feature, and showed the reasons why it is useful. We already know that the Theme Customizer has 4 main components: Settings, Sections, Controls and the one which controls the others is the Manager who's important variable is $wp_customize. We also know the way to invoke this variable for using later. In this tutorial, I plan to go deeply into these components, figure out their properties and how to register or remove components and the way to configure them as you want.



As said in the first part, this is an important component with the main task of managing the others. It initializes all necessary things, sets things up, and integrates the default components to the Theme Customizer. As it is an instance of the WP_Class_Customize_Manager class ( located in wp-includes/wp-class-customize-manager.php ), it has some useful methods:

Get all sections, settings or controls list:

$wp_customize->sections(); // return an array with the id is the id of section/setting/control,
$wp_customize->settings(); // and the value is Section/Setting/Control object.
$wp_customize->controls(); //

For getting a component, we could use:

$wp_customize->get_section( 'id' );
$wp_customize->get_setting( 'id' ); // Remember to pass the id as argument.
$wp_customize->get_control( 'id' );

Or remove components:

$wp_customize->remove_section( 'id' );
$wp_customize->remove_setting( 'id' ); // Remember to pass the id as argument.
$wp_customize->remove_control( 'id' );

Manager also has some other important methods including:

$wp_customize->add_section( 'id', array() ); // The first argument is the id of component
$wp_customize->add_setting( 'id', array() ); // The second one is an array of property-value pairs
$wp_customize->add_control( 'id', array() ); // passing to component object.

We will focus on these methods in the next sections.


As its name suggests, this component categorizes all settings into groups. Each section can contain one or many settings. This is the simplest component. Some methods that work with sections are add_section, get_section and remove_section:

$wp_customize->add_section( 'id', array(
	'title' => '',
	'description' => '',
	'priority' => ''
) );
  • id - A unique identity name, which will then be used with Settings and Controls.
  • title - The title of the section for display in the menu.
  • description - A short description about this section.
  • priority - The sequence or order of sections displayed in the menu, the lower the number, the higher it will display.

You notice that every section is an instance of the WP_Class_Customize_Section class ( located in wp-includes/class-wp-customize-section.php ), so if you use get_section, that method will return an object which is an instance of that class.

To get an available setting, just use get_section, this method returns a setting object.

$wp_customize->get_section( 'id' );

And the last method is remove_section, it simply removes any section we want to remove:

$wp_customize->remove_section( 'id' );

For example, if I would like to add a new section to use later, the following code is what I would do:

$wp_customize->add_section( 'wp_tuts', array(
	'title' => 'WpTuts',
	'description' => 'An example for Theme Customizer',
) );


These are components which control options, each handles a specific option. They're inside of sections and under the WP_Customize_Setting class ( located in wp-includes/class-wp-customize-setting.php ). The main task of this component is defining the way a setting is stored and where it should be saved. The following code is the syntax for this method:

$wp_customize->add_setting( 'id', array(
	'default' => '',
	'theme-supports' => '',
	'type' => '', // Default is "theme_mod"
	'capability' => '', // Default is "edit_theme_options"
	'sanitize_callback' => '',
	'sanitize_js_callback => '',
	'transport' => '', // Default is "refresh"
) );
  • default - The default value of the input setting field.
  • theme-supports - Check whether the current theme supports the given theme feature, if not, this setting is no longer available.
  • type - Define a setting's type, either theme_mod or option, the default is theme_mod.
    • theme_mod settings are only available in the current theme, they are all settings that maintain the current theme, and they are special for each theme. To get the value of specific settings, you might use the get_theme_mod function with an argument of the name of of a specific setting. Notice that the get_theme_mod function will change where it fetches data from every time we change themes, it also means that function is dependent on the theme we use. Say for example, when we use Twenty Eleven, the get_theme_mod function get data from the theme_mods_twentyeleven option, and the theme_mods_twentyten option if we use the Twenty Ten theme.
    • On the other hand, option settings will available everywhere, as you know, it's option that we usually use. To get the value, we use get_option: function, presumably you know this.
  • capability - The capability required for current settings to be displayed to the user. Read more about Roles and Capabilities
  • sanitize_callback - The callback function that sanitizes data input. Theme Customizer has an available function called sanitize_hex_color_no_hash that is used to check data input is a hex color without a hash.
  • sanitize_js_callback - The callback function that sanitizes data used for Javascript.
  • transport - The way data will be transported, can be either refresh or postMessage.
    • refresh - Every time there is something changed in the setting options, the Theme Customizer forces the Preview frame to reload, so the content in Preview frame will be totally refreshed.
    • postMessage - Instead of refreshing the whole Preview frame when something changes, the new data will be transported instantly to the Preview frame using JavaScript techniques.

So the reason that WordPress has these two ways to transport data (refresh and postMessage), is for the changes that have less impact on the page structure, or for simple changes (maybe add/remove something or change the value of some properties of HTML/CSS). We should use postMessage for these as they can be processed with JavaScript instantly and easily, without the need to reload the whole page. Conversely, if new changes to settings will effect the page structure, or are difficult for Javascript to do effectively, it's better to use refresh. Also let me know your thoughts about this by leaving your comments.

The following is a simple example of adding a new Setting:

$wp_customize->add_setting( 'blogname', array(
	'default' => get_option( 'blogname' ),
	'type' => 'option',
) );

Same as Section, we also have get_setting and remove_setting for Settings:

$wp_customize->get_setting( 'id' );
$wp_customize->remove_setting( 'id' );
// Ex: Get value of setting
$wp_customize->get_setting( 'blogname' )->value(); // Return website's name;


This component will arrange settings for proper sections, define the type of settings, and then render their content. Each control is an instance of the WP_Class_Customize_Control class ( located in wp-includes/class-wp-customize-control.php ).

$wp_customize->add_control( 'id', array(
	'label' => '',
	'settings' =>  // Default is id property.
	'section' => '',
	'type' => '', // Default is "text"
	'choices' => '', // This is optional, depending on type's value.
	'priority' => '', // Default is 10.
) );
  • id - A unique id for control, also to be used as the name of the setting option if the value of the following settings property is not defined.
  • label - The label of setting.
  • settings - The name of the setting option that is handled. If leaving blank, the value of above id will be used.
  • section - The section that the setting belongs to.
  • type - The type of setting option will be rendered. The Theme Customizer has some default values that you can use:
    • text - The kind of input setting option will be a text input type. This is also the default value if you don't pass anything for the type property.
    • checkbox - Rendering a checkbox setting option.
    • radio - Rendering a list of checkbox setting options. You need to pass an array of value/title pairs for each radio input as choices
    • select - Rendering a select setting option list. Like radio, its option list needs to be passed through the choices attribute.
    • dropdown-pages - It's a select list, however, was built for displaying the website's pages list option.
  • choices - List of setting options for the radio and select types.
  • priority - Used to specify the order in which a setting is displayed. Lower numbers correspond with earlier execution, and settings with the same priority are executed in the order in which they were added.

Getting and removing a control, just do as follows:

$wp_customize->get_control( 'id' );
$wp_customize->remove_control( 'id' );
// Ex: get value of setting that control manage
$wp_customize->get_control( 'blogdescription' )->value(); // Get website's description.

Ideas: Components are objects, working under classes. So we could extend these classes to modify or customize them in our own way. By default, Wordpress also has some extra components extending in this way. I will walk through them in later parts of this series.


In this series, I intended to show every single component along with its examples in action. However, it's hard to explain everything thoroughly because of the strict connection of components. So finally I decided to show the necessary informations for each component first, then give examples in action later, in the next part. Hope it don't make you feel boring. Again, I'm looking forward to hearing your comments, any and all feedback is much appreciated. Thank for reading!

Related Posts
  • Code
    Theme Development
    Custom Controls in the Theme CustomizerTheme customizer custom control 400
    In the last article, we explored the advanced controls available in the Theme Customizer, and how to implement them. We’re going to look at how to create our own custom control, allowing you to choose which Category of Posts are displayed on the home page. To get started, download version 0.6.0 of our Theme Customizer Example.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: Advanced ControlsTheme customizer 400
    Throughout this series, we've been taking a look at the Theme Customizer, how to implement it in our themes, how to save, serialization, retrieve settings, and how to implement the options so that they automatically refresh whenever the options are updated. As we begin to wind down the series, we're going to be taking a look at the advanced controls offered by WordPress, and how to implement one of them in our theme. Then we'll be reviewing some of the resources that are available for those of you who opt to consider researching, implementing, and leveraging the Theme Customizer in your day-to-day work. But first, let's begin by taking a look at some of the controls that are offered natively with WordPress.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: A Methodology for Sections, Settings, and Controls – Part 2Theme customizer 400
    In the last article, we defined a simple methodology for everything that's required to establish a new Section, Settings, and Controls within the Theme Customizer. In this article, we're going to continue with doing more of the same; however, we're going to be adding new settings and controls into the existing section, but we're going to be looking at a variety of different options such as radio buttons, select boxes, and input boxes. So with that said, let's continue.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: A Methodology for Sections, Settings, and Controls - Part 1Theme customizer 400
    At this point in the series, we've covered everything from understanding why the Theme Customizer is beneficial to those of us who are designers and developers, how to implement it in our theme, and understanding the relationship between sections, settings, and controls. We've also taken a look at how to implement our own setting and control into one of WordPress' predefined sections. In this article, we're going to take a look at what's required to introduce our own section and a variety of settings and controls. This article will cover a methodology that can be followed for implementing new settings and controls, and how to apply this methodology for introducing a new section, setting, and control. We'll expand on this topic in the second part of this article by introducing additional controls. But, for now, let's take a look at the methodology, and let's introduce a new setting into the Theme Customizer.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: Adding a New SettingTheme customizer 400
    By now, we've taken a look at what the Theme Customizer is, how it works, and the components that are unique to it. We've even discussed how options are serialized into the database so that we may retrieve them later when using our theme. To that end, it's time for us to begin doing our own work with the Theme Customizer. In this article, we're going to take a look at transports, how they work, and the difference in their two primary methods. Additionally, we're going to introduce our own control into one of WordPress' existing sections and see how it works with the various transport models.Read More…
  • Code
    Theme Development
    Digging Into the Theme Customizer: Practicing IIDigging into theme customizer part 4 practicing2
    In the previous post, we examined the Theme Customizer's component in actions. In this part, I would like to show you three additional things that I see as important for you about Sanitization, Transport, and some Extended components in the Theme Customizer. Before reading this, I recommend that you review the previous articles in this series.Read More…