Simple steps to create a Theme Option Page using The WordPress Settings API

Creating Your own WordPress theme is a great way to enhance the overall look and feel of your website. But irrespective of how enthralling your theme looks unless until it is not provided with the options that let you control its functions and appearance, it’s of no use. And it becomes even more critical when a paying customer is using your theme. Luckily, creating a settings page for your theme in WordPress isn’t an up hill battle. And, after reading this tutorial you’ll be able to do that.

WordPress theme customizer was introduced in the WordPress version 3.4 in the year 2012. WordPress settings API for the theme customization provides an editing environment to the developer where they can easily try theme options before being applied to the live website. It provides an easy way to play around with theme options and thus help them focus on keeping things simple.


In this post, I am going to show you some simple steps of creating a custom theme option page in WordPress using API. So, let’s take a look on how we can easily add settings to the theme via API.

1. Let’s Start from The Ground Level

Okay, it’s enough of theory, it’s time for some code. WP_Customize_Manager class provides basis for customization API, and this file can be accessed via $wp_customize object. There are various ways of creating a theme option page, and the most recommended one is to enclose all the settings in a class. For this, we first need to create a function in theme’s functions.php file, which will allow us to integrate our own additions into the customizer. The function needs to be included into custom_register file.

add_action( 'customize_register' , 'my_theme_options' );

function my_theme_options( $wp_customize ) {
// Sections, settings and controls will be added here

2. Defining Components for The Theme Settings

Each item you include into the customizer, needs to have these three components:

Section- for placing items
Setting- must be registered in Database
Control- For altering the defined settings

All three components are necessary to eliminate confusion when it comes to adding or manipulating components like colors, fonts in your theme settings.

3. Creating the Section Field

For creating sections there is a function called add_section() is used. It is further divided into two parts: a section slug and an array of arguments. Below is an example of creating a foot section in a theme.

'title' => __( 'Footer Settings', 'myfirsttheme' ),
'priority' => 99,
'capability' => 'edit_theme_options',
'description' => __('Change footer options.', 'myfirsttheme'),

The first parameter is the unique ID for that section which you’ll use later at the time of adding controls. In the second parameter, we have defined an array of options for the settings. The Priority section defines their order in the list.

4. Settings

Now, let’s configure some settings. Don’t confuse settings with controls as controls need to know the settings you are changing. So, we need to create settings first.

Here is how you can declare a setting:

$wp_customize->add_setting( 'myfirsttheme_theme_options[color_scheme]', array(
'default' => '#d8d8d8',
'type' => 'option',
'capability' => 'edit_theme_options',

There are a range of options which could be added here but for now this is fine. Remember, settings are not connected with controls. Settings are simply registered with database.

5. Controls

Finally, we come to controls. One can look at controls in a variety of ways, and there are reasons for that. In fact, WordPress defines a number of possible controls using various methods. Let’s have a look over some of them:

Radio Selection

$wp_customize->add_control( 'myfirsttheme_color_scheme', array(
'label' => __( 'Color Scheme', 'myfirsttheme' ),
'section' => 'myfirsttheme_color_scheme',
'settings' => 'myfirsttheme_theme_options[color_scheme]',
'type' => 'radio',
'choices' => array(
'value1' => 'Choice 1',
'value2' => 'Choice 2',
'value3' => 'Choice 3',

Quite simple right? The code above referencing the section it is associated with, and the settings which could be easily changed. Also, it has a radio type and a list of choice and their related values.

Creating Checkbox type Control

$wp_customize->add_control( 'display_header_text', array(
'settings' => 'header_textcolor',
'label' => __( 'Display Header Text' ),
'section' => 'header',
'type' => 'checkbox',
) );

Checkbox control comes directly from the core. It can be both enabled or disabled. It could be either true or false and does not require any real value.

This way you can create some more custom controllers to extend the class of your WP_Customize_control and adds the bit you want.

6. Settings Value

WordPress, by default, stores all the settings in theme_mod. Theme_mods are an alternative to the settings API, which makes the management of theme specific functions easy. It’s pretty simple to do, all you need is restore the value of a setting using the ID of the setting passed in theme_mod.

Let’s use CSS to add some edge to our website by using the saved setting:

add_action( 'wp_head' , 'my_dynamic_css' );

function my_dynamic_css() {


7. Getting Live Previews

Live previews is a function which does not come with WordPress by default. But it can be easily created using the below mentioned steps:
Enqueueing The Live Preview Script
For this, we need to use the customize_preview_init and must ensure that ‘jquery’ and ‘customize-preview’ are loaded before our script. Apart from this, it’s a standard enqueue highlighting the JavaScript file in our theme.

add_action( 'customize_preview_init' , 'my_customizer_preview' );
function my_customizer_preview() {
get_template_directory_uri() . '/js/theme-customizer.js',
array( 'jquery', 'customize-preview' ),

Adding Live Preview Support
Now, this one is pretty simple. Here, we need to first define a transport key for the arguments of our settings and then fix the value to the Post Message. This is how we can do:

$wp_customize->add_setting( 'footer_bg_color',
'default' => '#d8d8d8',
'transport' => 'postMessage'

8. Implementing Encapsulation within the class

Encapsulating in a class is a recommended method to write better functions and make code cross-theme compatible, so that multiple themes can work together. Here is how we can go about it:

class My_Customizer {
function register() {
// Sections, settings and controls will be added here
function header_output() {
// The live CSS is added here
function live_preview() {
// The live preview is enqueued here

add_action( 'customize_register' , array( 'My_Customizer' , 'register' ) );
add_action( 'wp_head' , array( 'My_Customizer' , 'header_output' ) );
add_action( 'customize_preview_init' , array( 'My_Customizer' , 'live_preview' ) );

Note that we have kept everything constant except some of the functions. Also, we are referring classes inside functions in our functions.php file.

That’s it! Hopefully you have enjoyed the article and will use it for the future reference.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.