Add WordPress customizer fields using Customizer API

We are getting a lot of requests for a tutorial on how to Add WordPress customizer fields using Customizer API. This will be a handy tutorial for the WordPress developer who loves adding WordPress customizer fields using Customizer API.

For those who are new to WordPress and don’t know what is WordPress customizer fields and what is Customizer API, we will explain this a bit. If you already know this then you can skip the following paragraph and directly jump to the coding part.

What are WordPress customizer fields?

If you ever opened the customize option under appearance then you might notice some fields (input, textarea, image upload, etc) under different sections like header settings. These settings are generally made by the theme. See the screenshot for your reference

For information on WordPress Customizer API, you can visit this link

They have nice documentation but for practically adding the code, you can ready throughout this tutorial. By the end of this tutorial, you will be able to add any customized field using WordPress Customize API.

In this tutorial, we will use a real-life example which is a very common requirement for almost all projects.

We will create a social link section that you can use anywhere on the website. In general, this is used in the header or footer of the website but it’s up to your requirement to use this anywhere you want.

Lets Start

Step 1 – Add customize_register action hook

First of all, we have to add a customize_register action hook which allows us to add the options for WordPress customize API. Add the following code to your active theme’s functions.php file

<?php
add_action('customize_register', 'dcs_customize_register');
/**
 * callback function to add customizer section
 * @param  object $wp_customize
 */
function dcs_customize_register($wp_customize) {
    //add all settings code here
    
}

Line number 1 is the action hook name “customize_register” and the second parameter is the name of the callback function. We have defined a blank function for a callback at line number 6 which we will fill section by section.

Step 2 – add a panel and section

Panels and sections are the wrappers for WordPress customizer fields. In the screenshot above, “Site Identity” is the section. To add this, copy and paste the following code in the above empty callback function.

<?php
// Create our panels
$wp_customize->add_panel('dcs_custom_header', array('title' => __('Custom Header', 'dcs'),));
// Create our sections
$wp_customize->add_section('dcs_header_section', array('title' => __('Header section', 'dcs'),));

Step 3 – Add settings and controls

Now we have a section ready with the name “Header section”. It’s time to add the fields inside this section. We will add three fields for

Facebook url
Twitter url
LinkedIn url

Add the following code to the same callback function under the above code.

<?php
// Create our settings

// Social fields

$wp_customize->add_setting("dcs_social_fb", [
    "type" => "theme_mod",
    "transport" => "refresh",
]);
$wp_customize->add_control("dcs_social_control_facebook", [
    "label" => __("Facebook", "dcs"),
    "section" => "dcs_header_section",
    "settings" => "dcs_social_fb",
    "type" => "text",
]);

$wp_customize->add_setting("dcs_social_linkedin", [
    "type" => "theme_mod",
    "transport" => "refresh",
]);
$wp_customize->add_control("dcs_social_control_linkedin", [
    "label" => __("LinkedIn", "dcs"),
    "section" => "dcs_header_section",
    "settings" => "dcs_social_linkedin",
    "type" => "text",
]);

$wp_customize->add_setting("dcs_social_twitter", [
    "type" => "theme_mod",
    "transport" => "refresh",
]);
$wp_customize->add_control("dcs_social_control_twitter", [
    "label" => __("Twitter", "dcs"),
    "section" => "dcs_header_section",
    "settings" => "dcs_social_twitter",
    "type" => "text",
]);

Up to this, your “Header section” is ready with all the three fields to be saved in the database.

Still, confused with adding code? Let me make it a bit more easy for you.

Just add the following code to your active theme’s functions.php file

/**
 * callback function to add customizer section
 * @param  object $wp_customize
 */
function dcs_customize_register( $wp_customize ) {
// Create our panels
$wp_customize->add_panel( 'dcs_custom_header', array(
'title'          => __('Custom Header', 'dcs'),
) );
// Create our sections
$wp_customize->add_section( 'dcs_header_section' , array(
'title'             => __('Header section', 'dcs'),
) );

// Create our settings

// Social fields

$wp_customize->add_setting( 'dcs_social_fb' , array(
'type'          => 'theme_mod',
'transport'     => 'refresh',
) );
$wp_customize->add_control( 'dcs_social_control_facebook', array(
'label'      => __('Facebook', 'dcs'),
'section'    => 'dcs_header_section',
'settings'   => 'dcs_social_fb',
'type'       => 'text',
) );

$wp_customize->add_setting( 'dcs_social_linkedin' , array(
'type'          => 'theme_mod',
'transport'     => 'refresh',
) );
$wp_customize->add_control( 'dcs_social_control_linkedin', array(
'label'      => __('LinkedIn', 'dcs'),
'section'    => 'dcs_header_section',
'settings'   => 'dcs_social_linkedin',
'type'       => 'text',
) );

$wp_customize->add_setting( 'dcs_social_twitter' , array(
'type'          => 'theme_mod',
'transport'     => 'refresh',
) );
$wp_customize->add_control( 'dcs_social_control_twitter', array(
'label'      => __('Twitter', 'dcs'),
'section'    => 'dcs_header_section',
'settings'   => 'dcs_social_twitter',
'type'       => 'text',
) );

}
add_action( 'customize_register', 'dcs_customize_register' );

Now we are ready with data stored for Facebook, Twitter, and LinkedIn URLs. It’s time to show the links as per this data. For that, we will use a shortcode that you can place anywhere you like.

Step 4 – Add shortcode

Simply add the following code to the active theme’s functions.php to add WordPress customizer fields data in the social URL links

/**
 * Shortcode to show the social links
 * based on values provided.
 */
add_shortcode("dcs_social_links","dcs_social_links_callback");
function dcs_social_links_callback(){
ob_start();

$dcs_social_fb = get_theme_mod('dcs_social_fb');
$dcs_social_linkedin = get_theme_mod('dcs_social_linkedin');
$dcs_social_twitter = get_theme_mod('dcs_social_twitter');

if($dcs_social_fb != ''){
echo "<a href='$dcs_social_fb'>Facebook</a>";
}

if($dcs_social_linkedin != ''){
echo "<a href='$dcs_social_linkedin'>LinkedIn</a>";
}

if($dcs_social_twitter != ''){
echo "<a href='$dcs_social_twitter'>Twitter</a>";
}

return ob_get_clean();
}

The above code will add a shortcode with the name “dcs_social_links”.

Step 5 – Place shortcode – dcs_social_links

Place the shortcode dcs_social_links where you want to show the social links.