How to Use the Customizer to Add/Update Theme Settings in WordPress

The WordPress customizer is an option that makes adding various settings for a custom theme quite easy.

If you do not know what is a customizer, it is a set of options provided by WordPress to control various settings and is accessible from Appearance > Customize.

The customizer screen is composed of four elements – panels, sections, controls and settings.

A setting is a value used for a theme feature. The other three – control, section and panel are user interfaces.

A control is used to input/update a setting. A section is used to group controls and a panel is used to group sections.

For example, you may have a setting for a custom background image. To update or set this setting you will need a user interface. A control for the setting will allow you to do that.

So where do these settings and controls, sections, and panels appear? As stated earlier, Appearance > Customize is the place to look for.

Setting

A setting is a theme option or feature. It is managed through a control.

The syntax for a setting is –

$wp_customize->add_setting( 'setting_id',
     array(
         'type' => 'theme_mod', 
         'capability' => 'edit_theme_options',
         'theme_supports' => '', 
         'default' => '',
         'transport' => '', 
         'sanitize_callback' => '',
         'sanitize_js_callback' => '', 
     )
);

The setting_id is a unique string that identifies the setting. It is a required parameter.

The type parameter can be theme_mod or option. The difference between these two values is the way they are stored in the database and how they are used.

Custom themes do not need to use the option type. It is because the theme-specific values can be handled through the theme_mod type. The option value is generally used for the whole site setting and is not limited to a specific theme.

The sanitize_callback parameter takes a custom function name which is used to sanitize and validate the input value for the setting. The type of sanitization is based on the control of the setting.

Control

A control is the user interface for a theme setting.

Controls are grouped inside a section – meaning, there can be multiple controls in a section.

A control is created with the following syntax –

$wp_customize->add_control( 'setting_id',
     array(
          'type' => '',
          'priority' => '', 
          'section' => 'section_id', 
          'label' => '',
          'description' => '',
          'input_attrs' => array(
               'class' => '',
               'style' => '',
               'placeholder' => '',
           ),
          'active_callback' => '',
     )
);

Here setting_id is the id of the theme setting it is handling. It is a required parameter.

The type parameter controls the control type. It can be one of the following types –

text
textarea
checkbox
radio
select
dropdown-pages

The priority parameter decides in which order the control will be shown respective to its section. Usually values from 10 – 100 are used, but you can experiment.

The label and description parameters can be any arbitrary strings you want.

The input_attrs parameter helps to add a few custom values to the control – class is a CSS class name, style is CSS inline styling rules and placeholder is self explanatory.

The active_callback parameter allows us to show or hide this control based on true/false value from a callback function.

We can write a custom callback function there. If the function returns true the control will be shown, else it will be hidden.

'active_callback' => 'custom_active_callback'

In the code above custom_active_callback is a function that will return either true or false.

The condition for truth or falsity of the callback function is based on what is on display in the site previewer window in the customizer.

Say, you want to show the control only when archive pages are on display in the previewer. In that case you can write the custom callback function like this –

function custom_active_callback() {
   if ( is_archive() ) return true;
   else return false;
}

This will show the control when archive pages are previewed with the customizer and hide the control for all other posts and pages.

By the way, this custom function can be placed anywhere in the functions.php file.

Section

A section is used to group one or more controls. You can create a custom section or use one already present in core WordPress.

The syntax to create a section –

$wp_customize->add_section( 'section_id',
   array(
       'title' => '',
       'description' => '',
       'panel' => 'panel_id', 
       'priority' => '',
       'capability' => 'edit_theme_options',
       'theme_supports' => '',
   )
);

The title and description are any arbitrary strings ( usually descriptive ). The priority parameter decide where the section appears on the sidebar customizer screen.

The capability parameter tells you the capability required to create this section. Usually it is edit_theme_options.

The panel_id is optional. If you skip it, the section will be shown on the top level of the customizer screen.

For a new theme without any data, WordPress shows a few default sections on the customizer screen. These are –

Site Identity
Homepage Settings
Additional CSS

The section Ids of these sections are as follows –

title_tagline	Site Identity
static_front_page	Homepage Settings
custom_css	Additional CSS

With add_theme_support more sections are added to the customizers screen. The add_theme_support is an inbuilt function used to add various features to a theme.

add_theme_support(‘custom-logo’)	Adds a Logo feature inside Site Identity in customizer
add_theme_support(‘menus’)	Adds Menus section in customizer
add_theme_support(‘custom-header’)	Adds a Header Image section in customizer
add_theme_support( ‘background_image‘ )	Adds Colors and Background Image sections to the customizer

If you want to use these existing sections then you have to know their section ids.

Section ID	Section Label in Customizer
title_tagline	Site Identity
colors	Colors
header_image	Header Image
background_image	Background Image
nav	Menus
static_front_page	Homepage Settings

Core Section Ids in Customizer – WordPress

Panels

The panels are top level display elements in the customizer. Basically a panel is used to group sections based on context.

The syntax for a panel is –

$wp_customize->add_panel( 'panel_id',
   array(
       'title' => '',
       'description' => ''
       'priority' => ''
   )
);

The title parameter takes a string any can be anything descriptive of the panel. The description also takes any arbitrary string.

The priority parameter decides the order in which the panel appears in the customizer sidebar and takes a number. Usually you can put 100 or more than that for this parameter.

Custom themes are not required to add panels.

Any setting that a custom theme needs to add, can be done through custom or existing sections.

A custom theme can have a section or sections without a panel. The section(s) will then show up in the topmost screen of the customizer.

Putting everything together

You have got the code for creating setting, control, section and panel. But where do you put these code blocks? And what is $wp_customize that we are using the create the elements?

The place is your functions.php file or anywhere that is within the scope of functions.php

And these code blocks do not work on their own. You will need a hook to make these work.

add_action( 'customize_register', 'tornadu_customize_register' );

Here customize_register is the required hook and tornadu_customize_register is the custom callback function for this hook.

Using the customize_register hook exposes an object $wp_customize to the custom callback function which is then used to create the elements.

You will write the code for generating settings, controls, sections and panels within the custom function.

function tornadu_customize_register( $wp_customize ) {
    // call to create a panel
    // call to create a section
    // call to create a control
    // call to create a setting
}
add_action( 'customize_register', 'tornadu_customize_register' );

A setting needs a control and a section to be visible. So to create a setting you need at least one control and one section.

The panel is a top level user interface that is used to group sections but usually not used in a custom theme.

So the complete code for creating a setting looks like this –

// Optional - you can skip creating this
$wp_customize->add_panel( 'awesome_panel', // required if new panel is to be created
   array(
       'title' => 'My Awesome Panel', // any arbitrary string
       'description' => 'An awesome panel' // any arbitrary string
       'priority' => 10 // optional - can be skipped
   )
);

// create a section - optional, can take an existing section
$wp_customize->add_section( 'section_id',
   array(
       'title' => 'My Awesome Section', // any arbitrary string
       'description' => 'An awesome section', // any arbitrary string
       'panel' => 'awesome_panel', // optional - can be skipped 
       'priority' => 100,
       'capability' => 'edit_theme_options', // optional - can be skipped
       'theme_supports' => '', // optional - can be skipped
   )
);

// create a setting - required
$wp_customize->add_setting( 'awesome_setting', // required
     array(
         'type' => 'theme_mod', // optional - can be theme_mod or option
         'capability' => 'edit_theme_options', // optional - can be skipped
         'theme_supports' => '', // optional - can be skipped
         'default' => 1, // required - value can be different based on the type
         'transport' => '', // optional - can be skipped
         'sanitize_callback' => '', // required - takes a function call
         'sanitize_js_callback' => '', // optional - can be skipped
     )
);

// create a control - required
$wp_customize->add_control( 'awesome_setting', // required - the setting id
     array(
          'type' => '', // required 
          'priority' => '', // optional - can be skipped
          'section' => 'awesome_section', // required - the section id
          'label' => 'My Awesome Section Label', // any arbitrary string
          'description' => 'My Awesome Section Description', // arbitrary string
          'input_attrs' => array( // optional - can be skipped
               'class' => '',
               'style' => '',
               'placeholder' => '',
           ),
          'active_callback' => '', // optional - can be skipped
     )
);

Creating a section and a panel are optional because you can use an existing section/panel. In that case you just need the ids of the existing section/panel.

You can actually skip creating or using a panel at all. When you do not use any panel, then the section shows up at the topmost level of the customizer screen.

When you use an existing section then you must know the id of that section to be used with your controls.

In a brand new theme started from scratch, WordPress generates a few default sections –

Site Identity
Homepage Settings
Additional CSS

These sections contain controls that are associated with a few settings like site title, tagline, showing posts or a static page on the home page, and additional CSS for the site.

As stated earlier, with add_theme_support function, you can add more core sections to the customizer. The Core Section Ids in Customizer – WordPress table contains ids of these section.

Guide Wordpress