One of WordPress 3.4’s best new features is the Customizer which allows you to create a place where the theme itself can be updated or modified. The Customizer, also called a theme options panel, is an area in the admin with a list of sections and options to the left in a panel, and a preview of the theme’s homepage to the right. The preview of the site on the right actually updates immediately when changing the options on the left. The Customizer allows you to fine tune the theme options and really customize the theme without having to know how to code. The coolest part about the new Customizer, is that while you tweak your options and settings in the left hand panel, you can see the changes take effect on the right, before you even save them! These panels are fantastic if you plan to distribute your themes widely, but they’re also very helpful even if it’s a single theme for a single site. Before WordPress 3.4, you actually had to build the options panel manually, which took a lot of time, didn’t match the rest of WordPress’s look and feel and were generally quite annoying to deal with.

The Customizer can be used to set up the URLs for social media links, the footer’s copyright notice or even the entire theme’s color scheme! You can use text inputs, color pickers, radio buttons, checkboxes and dropdown menus in the Customizer, but unfortunately, there’s no way to add full textareas or support for entering HTML. While the Customizer is a fantastic addition to WordPress, for some reason the WordPress creators decided to hide the function in a funky place. To get to it, you simply need to click on Appearance > Themes from your Dashboard, and then you’ll see a link to “Customize” your theme next to the theme’s thumbnail.

When starting with a blank theme, you may have noticed that the Customizer already comes with a couple of default groups and options. These are the Site Title & Tagline section, which allows you to set the theme’s title and tagline, and the Static Front Page section, which allows you to choose whether to display the blog or a regular page as the homepage. Unfortunately, these can’t be removed from the Customizer, but I’ll talk about how we can order our options, to make it a bit easier for you to find your way around.

Creating Sections

The first thing you’ll need to do before you can start adding in options, is to create a section for your options, which help to organize your options.

function themename_customize_register($wp_customize){
    $wp_customize->add_section('themename_section_name',array(
        'title' => __('Section Title', 'themename'),
	    'priority' => 120,
	));

}

add_action('customize_register', 'themename_customize_register');

Of course, make sure you replace ‘themename’ with your themename – this helps keep your code separate from the core and ensures your code doesn’t conflict with anything. The priority of a section tells WordPress in what order to place it in the admin area. Remember how I mentioned that we couldn’t get rid of the default sections of Site Title & Tagline and Static Front Page? We could change the priorities of our custom sections to be placed above those two default sections. Anything under 120 will be placed on top of those.

Different Customizer Options

Now that we’ve got our sections created, it’s time to start adding options. I’ll walk you through how to add different types of options.

Color Pickers

// Theme Colors

	$colors = array();

	$colors[] = array(
		'slug'=>'main_color',
		'default' => '#075f69',
		'label' => __( 'Main Theme Color', 'doxie' )
	);

	$colors[] = array(
		'slug'=>'secondary_color',
		'default' => '#fffff',
		'label' => __( 'Secondary Theme Color', 'doxie' )
	);

	$colors[] = array(
		'slug'=>'tertiary_color',
		'default' => '#6b4015',
		'label' => __( 'Tertiary Theme Color', 'doxie' )
	);

	foreach($colors as $color) {
		$wp_customize->add_setting( $color['slug'], array(
			'default' => $color['default'],
			'type' => 'option',
			'capability' => 'edit_theme_options'
		));

		$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, $color['slug'], array(
			'label' => $color['label'],
			'section' => 'doxie_theme_colors',
			'settings' => $color['slug'] ))
		);
	}

In this example, you can see that each option requires two functions:

  • add_setting-This creates the actual option and is where we give it its default state and the type of option it is. Capability will always be edit_theme_options, as this is what adds it to the customizer.
  • add_control– This function actually adds the option to the section of your choosing. label controls the label of the option in the front end, section is the name of the section you want it added to, and settings is the name of the option.

WP_Customize_Color_Control is what changes these options from a basic text option to a usable color picker. Because we’ve placed our colors in their own array, we can easily add or remove color options in the future.

Default values in the Customizer can be pretty confusing, because although they look like they do something, they actually don’t. If you were to leave the default values in the options, like the colors we just added in, and tried to display them in the front end, nothing would happen. We would actually want to put the correct three colors into the main CSS, so that they show up if no one decides to update them in the Customizer. So the default values are just meant to show what the developer has set as the default somewhere else. Once you get to playing around with the options more, this will become a bit clearer.

Adding Text Fields For Controlling Global Content

Now that we’ve got our color pickers in place, let’s move on to some more options styles. If you want to be able to input specific content, for example our social media URLs or the copyright notice for our example, you’ll need to use a text input. Creating these fields is very similar to the way we created our color pickers, except we remove the instance of WP_Customize_Color_Control from $wp_customize->add_control. Here’s an example for adding a Twitter username field.

	$wp_customize->add_setting('doxie_theme_options[doxie_twitter]', array(
	    'default'        => 'Add your URL here',
	    'capability'     => 'edit_theme_options',
	    'type'           => 'option',
	));

	$wp_customize->add_control('doxie_twitter', array(
	    'label'      => __('Twitter', 'doxie'),
	    'section'    => 'doxie_social_media',
	    'settings'   => 'doxie_theme_options[doxie_twitter]',
	));

Adding the text inputs to the front end is exactly the same as it is for the color pickers. We’ll simply assign get_option(‘doxie_theme_options’) to a variable of $options which will allow us to assign it once, but be able to use it multiple times.

Adding Radio, Checkbox & Dropdown Options

The only difference between text input fields and other types of the inputs is the addition of the type and choices parameters to the add_control function.

Type allows you to specify what sort of option you want, like checkbox, radio or select. The exclusion of the type parameter is what displays a text input. Although you could technically choose to tell WordPress to display the option as an text input, it’s not necessary since it’s the default.

Choices is required, when using on radio or select, and allows the user to select between different options. The choices are written inside of an array, with their value to the left and label to the right.

// Dropdown setting

$wp_customize->add_setting('doxie_theme_options[doxie_bkg]', array(
    'default'        => 'blue',
    'capability'     => 'edit_theme_options',
    'type'           => 'option',
));

$wp_customize->add_control('doxie_bkg', array(
    'label'      => __('Background Image', 'doxie'),
    'section'    => 'doxie_global_options',
    'settings'   => 'doxie_theme_options[doxie_bkg]',
    'type'    => 'select',
    'choices'    => array(
        'blue' => 'Blue Textured',
        'yellow' => 'Yellow Textured',
        'pink' => 'Pink Textured',
    ),
));

// Radio

$wp_customize->add_setting('doxie_theme_options[doxie_sidebar]', array(
    'default'        => 'value1',
    'capability'     => 'edit_theme_options',
    'type'           => 'option',
));

$wp_customize->add_control('doxie_sidebar', array(
    'label'      => __('Sidebar Position', 'doxie'),
    'section'    => 'doxie_global_options',
    'settings'   => 'doxie_theme_options[doxie_sidebar]',
    'type'    => 'radio',
    'choices'    => array(
        'value1' => 'Left',
        'value2' => 'Right',
    ),
));

// Checkbox

$wp_customize->add_setting('doxie_theme_options[doxie_image]', array(
    'default'        => '',
    'capability'     => 'edit_theme_options',
    'type'           => 'option',
));

$wp_customize->add_control('doxie_image', array(
    'label'      => __('Replace image of Dachshund with animated cat GIF?', 'doxie'),
    'section'    => 'doxie_global_options',
    'settings'   => 'doxie_theme_options[doxie_image]',
    'type'    => 'checkbox',
));

Displaying them in the front end

Now it’s time for the fun part, adding it to the CSS and the front end so that we can actually change our colors! First things, first though – we need to go ahead and add in some defaults to our style.css page, so that if we decide not to change our colors in the Customizer, we won’t be staring at a blank theme. This is especially important for when the user first installs the theme, it gives them some defaults to work with. I’ve created three CSS classes to keep up with our colors.

/****THEME COLORS*******/

.mainColorText { color: #075f69; }
.mainColorBkg { background: #075f69; }

.secondaryColorText { color: #fff; }
.secondaryColorBkg  { background: #fff; }

.tertiaryColorText  { color: #6b4015; }
.tertiaryColorBkg  { background: #6b4015; }

If you’re a CSS semantics nut like I am, you may be wondering why I decided to name my classes this way. Semantics are important for reusable code and describing the content within, but in this case, it was better to use something that was easily understandable and would make for shorter code in the CSS, instead of chaining hundreds of classes to one style. Plus, using mainColorText and so forth is still relatively semantic, as it does describe what’s in the element, and if we change our colors or our theme, it doesn’t become irrelevant.

Once we have our defaults set in the CSS, we can now set up our code to grab the colors from the Customizer if anyone changes them. It’s important that we use an if/else statement here, so that the default values will be used if nothing is set at all.
In order to add our color picker functions, we’ll need to set up the CSS inside of our header.php file because we can’t access PHP code inside of our styles.css page. We can do this with a simple style tag inside of our HTML head. The easiest way to move things over, is to simply copy and paste our color styles from style.css into the head. We’ll replace the colors with our functions in a bit

In order for us to use the Customizer color picker styles, we need to save them inside of some basic PHP variables using the function get_option and the name if the option above our style tags. This will also allow us to also create the if/else statement, so we’re not showing empty code if we’re not using it.

<?php
	$content_main_color = get_option('main_color');
	$content_secondary_color = get_option('secondary_color');
	$content_tertiary_color = get_option('tertiary_color');
?>

Then we just need to replace our hex colors with the variables we created in the code. I’ve also separated each set of colors out, with their own if/else statement that checks to see if the option has been changed, so that we execute the least amount of code as possible. For example, if you change just one color in the Customizer, only that color’s styles will show up in the header.php to be executed in the browser. If none of them are changed, then nothing happens and it defaults to the styles in the CSS. And remember, we don’t even have to save the options panel for it to update, WordPress will actually update the settings in real time so we can preview what our theme will look like!

<style>
	     .mainColorText { color: <?php echo $content_main_color; ?>; }
	     .mainColorBkg { background: <?php echo $content_main_color; ?>; }

	     .secondaryColorText { color: <?php echo $content_secondary_color; ?>; }
	     .secondaryColorBkg { background: <?php echo $content_secondary_color; ?>; }

	     .tertiaryColorText { color: <?php echo $content_tertiary_color; ?>; }
          .tertiaryColorBkg { background: <?php echo $content_tertiary_color; ?>; }

</style>

But wait, there’s more!

There are even more options I didn’t get into – you’ve got image uploaders as well! I’ll leave it to you to use the WordPress codex to find out the rest. Happy coding!

Amber Weinberg

Amber is a freelance front-end developer specializing in semantic and accessible custom WordPress themes. She works with agencies and other freelancers to bring their designs to life using custom ACF flexible layout builds - making them more performant and less buggy while allowing the client easy customization without breaking the design system.