1. Code
  2. Theme Development

A Guide to the WordPress Theme Customizer: Sections, Settings, and Controls

Read Time:7 minsLanguages:
This post is part of a series called A Guide to the WordPress Theme Customizer.
A Guide to the WordPress Theme Customizer: Getting Started
A Guide to the WordPress Theme Customizer: Adding a New Setting

In the last article, we created a very basic theme that included the Theme Customizer so that we could see how it looks within the context of the WordPress Dashboard.

After tinkering around with the provided options, it's easy to see just how powerful this particular feature can be. Generally speaking, this single feature can allow us to steer users away from complicated options pages and allow them to see the result of their changes as soon as they make them without having to hop back and forth between the dashboard and the public-facing side of the site.

And as much fun as it is to begin writing code to bring new features to life, it's important to understand what we're working with before we begin actually doing work with it, right?

So in this article, we're going to take a survey at what goes into working with the WordPress Theme Customizer. By the time you finish this article, you should have a clear understanding of the Theme Customizer, and how to begin introducing your own settings into existing sections, creating new sections, as well as some of the built-in controls that are available for us to use in our work.

Components of the Theme Customizer

In short, there are three components that go into creating the interface of the Theme Customizer. These are:

  1. Sections
  2. Controls
  3. Settings

We'll be taking a look at each of these in-depth in just a moment, but it's important to understand that this is not completely different from the Settings API.

In fact, I recommend going back and reading through that series especially if you're going to be introducing the Theme Customizer into a theme that uses the Settings API.

I mention this because as we begin to take a look at the Theme Customizer, we're going to cover some information that shows how you can tie the Theme Customizer to existing options.

On the other hand, if you're not currently using the Settings API - no worries! The Theme Customizer will take care of serializing all of the options for you such that you'll be able to retrieve them programmatically elsewhere in your theme.

Theme Customizer ComponentsTheme Customizer ComponentsTheme Customizer Components

Theme Customizer Components

But before we discuss any of that, let's talk about the components of the Theme Customizer.


Notice in the illustration above, we have three different sections, one of which is expanded:

  1. Site Title
  2. Colors
  3. Layout

Obviously, your mileage may vary depending on how your theme is setup, or how you're building your theme. But the point is that sections are made up of controls and settings each of which we'll talk about in more detail momentarily.

Perhaps the most important thing to note when adding settings to sections is that WordPress actually has several sections that it already provides. For example:

  • title_tagline - this section is used to hold the site title and tagline (sometimes referred to as the blog name or the description).
  • colors - is a section that's used to hold settings for particular controls related to settings for text color, link colors, and so on.
  • header_image - is used to hold controls responsible for allowing users to specify a header image.
  • background_image - this section is used to hold controls responsible for setting a background image.
  • nav - is the section that will give users the ability to customize their menus.
  • static_front_page - gives users the options necessary to set a static front page or a blog page, when needed.

Although it's completely possible - and common - to create your own sections (which we'll be doing later in this series), I mention these here so that when it comes time to begin introducing Settings, you don't reinvent the wheel of having one that's already provided.

Case in point: Let's say that you want to introduce a feature that lets users change the colors of links in their blog. It'd make sense to place this in the colors section that's already provided rather than, say, create your own section.

It's all about knowing when to use what's provided and when to create something that you need unique to your blog.


Simply put, a 'control' is a more-or-less fancy word for an HTML element that allows the user to manipulate something on the blog. That can be anything from an input element to a textarea, or a checkbox, to a color picker.

WordPress gives you the ability to easily use any of the most common HTML controls as well as create your own controls (which is out of scope of this particular article).

As far as controls go in the overall system of the Theme Customizer, controls represent the value of a setting and they belong to a single section.

For example, by looking at the illustration above you notice that we have a text input control. This control is responsible for representing the value of the title setting, and it belongs to the "Site Title" section.

Easy enough, right?


Finally, settings are synonymous with options - in short, they are the values that users tweak or change whenever they are trying to make customizations to their blog.

In case it isn't clear, note that settings are represented by a control and can only belong to a single section (since controls can only belong to a single section).

Now, here's where it can get somewhat complicated especially if you're working with the existing Settings API, or if you're starting a theme from scratch using the Theme Customizer.

By default, the Theme Customizer uses the theme_mod features to store all of the theme's values into a single database row. You can read more about get_theme_mod and set_theme_mod on their respective Codex articles.

Generally speaking, note that all theme_mod records are kept in the wp_options table with the key theme_mods_{theme-name} format. This means that you can easily look up the serialized options using a database front end or by running an SQL query.

For example, let's say we're using our Theme Customizer Example that we began creating in the last lesson. To see the setting values stored for that theme, you could run the following query:

Or, again, you could browse using a database front end.

If, on the other hand, you're going to be introducing the Theme Customizer with options that are already being used by the Settings API, it's very easy to integrate those into the customizer, as well. The primary difference is that rather than using theme_mod, you'll be using the Options API so all data will still be kept in the wp_options table, but will be retrieved by using get_option.

The nice thing about this is that all settings are contained within a single row in the database, and that you can retrieve the values based on their key using get_theme_mod.

Put It All Together

I contemplated showing how all of this fits together within this article, but I didn't want to risk including too much information in the article. As such, I wanted to lay a foundation for the three components of the WordPress Theme Customizer so that we have clear terminology and definitions when we begin to write code.

After all, how we can effectively understand the code we're writing if we're not even sure what some of the terms are? Then again, this would probably make more sense within the context of some example code.

Up Next...

To that end, in the next lesson, we're going to take a look at exactly how to implement our own section, control, and setting into the Theme Customizer.

We'll also take a look at the various transport methods that are available to us which are basically how the updates are shown to the user. At any rate, it's nothing too complicated, but we'll be putting all of the above into practice in the next article.

So if you've not caught up on the series thus far, now's the time as we're going to begin writing a lot of code in the next articles.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.