Add Customizer Settings to Underscores

While my blog runs on Ghost, 99% of the client work I do is WordPress related, and when I’m doing client work and need to develop a theme I use Underscores.


If you work with WordPress for a living and even remotely do theme work but have not heard of Underscores you probably live under a rock. It’s not the best tool for everyone, but for me and a lot of others it does a great job of giving you a starter theme for WordPress that does not include too much bloat.

WordPress Customizer

Another great tool in WordPress is the theme customizer. This removes the need to have to create your own theme options page or panel and trying to deal with saving the options… its a basic place to add the basic settings a theme may have.

Combining the Two

Recently I was asked for a good resource of how to add cusotmizer options into the Underscores theme. I searched Google to find a quick result and there really was not one. There were various articles on how to use the customizer but for someone just getting started they were a bit advanced.

Underscores comes “Customizer Ready” out of the box!

If you are using Underscores, then adding options to the customizer is very easy! Underscores already includes a separate file (inc/customizer.php) from within the
functions.php file. This file already has the relevant actions setup and is ready for you to add your own options.

The Situation

Right now I am working on a site for a client where there are social media icons in the top of the site. I want these icons to appear if a link has been provided in the customizer options. So we will need to do a few things here:

  • Add a Social Media seciton to the customizer
  • Add a setting for each social media icon to the Social Media section
  • In the theme’s header.php file check for the setting and conditionally output the link/icon

Open the file inc/customizer.php and find the function named _s_customize_register. Depending on how you downloaded Underscores the function name may vary slightly but will always end in _customize_register. By default this code has just a few lines which are simply changing the transport method of the default settings. These are not required and for our purposes you can just remove them… or leave them there… its up to you!

$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';

First we are going to add our Social Media section to the customizer. To do this we will use the $wp_customize->add_section() method. Simply pass an ID to the section, and then an array of arguments including the title, priority, and description. In this case the ID is social-media, the title is Social Media, the priority is 30, and the description explains to enter the URL for each services account for the icon to appear in the header.

// Add Social Media Section
		'title' => __( 'Social Media', '_s' ),
		'priority' => 30,
		'description' => __( 'Enter the URL to your account for each service for the icon to appear in the header.', '_s' )

Now that the section is added we need to add some settings using the
$wp_customize->add_setting() and $wp_customize->add_control() methods.

Just like with the section we will add the setting with two arguments: an ID, and an array of arguments. In this case the ID is twitter and the only argument we are passing is that the default is an empty string.

Next we add the control which is actual form elements for the setting in the customizer. The $wp_customize->add_control() method can either take an ID and an array of arguments or just a “specific customization controller object” – we will use the controller object. The WP_Customize_Control class will give us just a basic textbox like we want. In this class we will pass the $wp_customize variable that and, again, an ID and an array of arguments. The ID is twitter, and in the array we pass the label Twitter, the section social-media, and the settings ID again twitter.

// Add Twitter Setting
$wp_customize->add_setting( 'twitter', array( 'default' => '' ) );
$wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'twitter', array( 'label' => __( 'Twitter', '_s' ), 'section' => 'social-media', 'settings' => 'twitter', ) ) );

Repeat this last bit with the setting and control as many times as you would like to add as many settings as you would like. If you save the file and opening your customizer you should see settings!


Now that we have settings that we can save we need to add the icons to our header.php and show them only if there is a value saved. Just like the settings repeat this code as needed for all your settings.

This part is very simple, we use the get_theme_mod() function to get the setting from the customizer. Then if the setting is not empty, add the link and icon! In this code I am using the Font Awesome icons.

<a class="twitter" href='GHOST_URL/%22%3E

Thats it!

Simple enough right!