How to add options to the WordPress Customizer

How to add options to the WordPress Customizer

One of the great advantages of using WordPress is the abundance of avenues to accomplish the same outcome. This especially rings true when adding options to your theme. I used the Options Page functionality of the Advanced Custom Fields plugin quite effectively for some time, but I had been thinking about using the Customizer instead.

Switching to a new system of development is always hard; there’s a learning curve, which means investing time (and I already feel like I never have enough of it). So why change? If it ain’t broke, don’t fix it, or something like that, right?

Reasons for using the Customizer

  1. If at all possible, I try to make themes that are not dependent on plugins. This is especially true if a plugin has far more features than I need for the purpose of my theme. If the only feature of ACF I used was the Options Page, there was a better way – the Customizer.
  2. WordPress has been pushing people to use the Customizer for some time, so jumping on board is wise. Accomplishing consistency with the user experience is invaluable to the WordPress community, as a whole. If the platform is universally used as intended, we are all able to limit the potential bugs affecting our users’ sites as they make upgrades.
  3. Taking advantage of the live preview is a win for clients. This tool helps give our clients confidence in making changes to their websites by giving them a look at the adjustments in real time. If they can see the effects of their changes right in the moment, they can move forward on their own without needing additional assistance from us.

Using the Customizer was a bit overwhelming at first, but once I dove in, I found it easier than expected. So let’s break it down – here’s how to use the Customizer for theme options.

Pro-tip: The codex Theme Customization API is a great resource as well.

Remember: You should never make changes on a live site. Our free local development app, Local by Flywheel, will help you simplify your workflow and safely experiment with your site. Try it today!

Structuring theme files

The following code should go into your functions.php file, or I personally like to create a new file specifically for this information in order to keep my functions.php file from getting too cluttered.

Here are the files I have in my theme folder that I’ll be referencing:

  • header.php
  • functions.php
  • inc/customizer.php

In my functions.php file, I include the following line so that it will load my Customizer file:

/**
* Customizer additions.
*/
require get_template_directory() . '/inc/customizer.php';

Add the settings and controls

wordpress-customizer-site-identity-default

Now, let’s discuss how to add controls and settings to the Customizer. One of the options I always include in my themes is the ability to upload a logo. This is a cornerstone for any business site. By default, WordPress includes a Site Identity panel with a site title/tagline section in the Customizer. This is where we will add our logo field, using the customize_register hook.

wordpress-customizer-site-identity-options

We are going to create a unique function that adds the setting so that WordPress knows to store a new value, and then add the control for this setting to the Site Identity panel in the Customizer.

/**
* Create Logo Setting and Upload Control
*/
function your_theme_new_customizer_settings($wp_customize) {
// add a setting for the site logo
$wp_customize->add_setting('your_theme_logo');
// Add a control to upload the logo
$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'your_theme_logo',
array(
'label' => 'Upload Logo',
'section' => 'title_tagline',
'settings' => 'your_theme_logo',
) ) );
}
add_action('customize_register', 'your_theme_new_customizer_settings');

The fields will now appear in the Customizer for your theme, but we also need to include the logo in the template files.

wordpress-customizer-site-identity-logo

Use the option in your theme’s template files

So in header.php where you want the logo to appear, you’ll want to insert some code along these lines:

<?php
// check to see if the logo exists and add it to the page
if ( get_theme_mod( 'your_theme_logo' ) ) : ?>

<img src="<?php echo get_theme_mod( 'your_theme_logo' ); ?>" alt="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" >

<?php // add a fallback if the logo doesn't exist
else : ?>

<h1 class="site-title"><?php bloginfo( 'name' ); ?></h1>

<?php endif; ?>

Well done! Your logo will now appear in your theme.

wordpress-customizer-logo-example

Adding additional panels

You can also add additional panels to the Customizer to better organize your options. I try to think through what is most intuitive and organize accordingly. WordPress includes the following panels/sections by default:

  • themes – Name of the theme
  • title_tagline – Site identity
  • colors – Colors
  • header_image – Header image and site icon
  • background_image – Background image
  • static_front_page – Static front page

By including the following code in your unique function from the instructions above, you can create a new panel.

// Add Footer Section
$wp_customize->add_section('your_theme_footer', array(
'title' => 'Footer',
'description' => '',
'priority' => 120,
));

It’s important to note that a panel will not appear unless there are settings and controls assigned to it. So make sure to add a control using 'section' => 'your_theme_footer', or whatever you named your new section.

Easy-peasy, right?

So there you have it, go test your new found skills and add some options to your theme using the Customizer.

16 Comments

  • Hey Krissie,

    Nice post there. Good for beginners to get started.
    It will be nice to add esc_url for get_theme_mod that outputs image URL.
    It’s not required but a good practice to have proper escaping.

    Thanks!

  • Eric says:

    thanks!
    needed this

  • Eric Njanga says:

    I’ve been reading through the customizer API and find this article somewhat complementary because of its simplicity in clearly demonstrating how to get up and running with WordPress customizer.

    Great article Krissie!

  • By putting get_theme_mod( ‘your_theme_logo’ ) twice in your theme file, are you not doing unnecessary database calls? Unless it’s cached, I think it’s better to save the result of get_theme_mod() in a variable and then using that instead of calling the function twice.

  • Dario says:

    Hi, thanks for this useful and easy to understand article. I’m trying to add an option for uploading an header image, but it seems doesn’t work. This is the code i wrote:

    $wp_customize->add_control( new WP_Customize_Header_Image_Control( $wp_customize, ‘header_image’, array(
    ‘label’ => __( ‘Header image’, ‘theme’ ),
    ‘section’ => ‘header_image_settings’,
    ‘settings’ => ‘header_image_position’,
    )
    ) );

    Where am i wrong?
    Thanks in advance.

  • Thanks for sharing great customization feature you can share with us.

  • Rushax says:

    Took me a little while to realise I needed to declare the
    <?php at the start of the inc/customizer.php document but this article was extremely helpful!
    Thanks so much.

  • Noor Ullah says:

    Very nice article! I will do use this featuristic approach to add social media like & Subscribe system into my theme.

  • Tem says:

    Thank you! This article helps me!

  • Rahman says:

    Thank you so much for your tutorial. It’s very helpful article.

    Thanks again

  • Ryan says:

    Hello,

    This article was pretty informative on the basics of utilizing the WP_Customize object.

    I had a question, say you’re adding onto a theme that uses existing settings.

    I’d like to add options to an already existing control defined on the theme.

    I know I should probably utilize the customize_register action hook to do this, but when trying to re-declare the option itself with the new choices it’s not working.

    Do you know how this is possible?

    Thanks

    • Ryan says:

      Ah nevermind, I was able to figure this out by setting a priority value on the hook itself and setting an additional priority value within the add_control method. This allowed me to override the initial control declaration but also keep it at the top with the add_control priority value.

  • Chalo says:

    Very Helpful, thank you for publishing this tutorial, excellent!

  • Andrew says:

    I am curious. I use ACF for a lot, including the theme options stuff. Is there a way to create the theme options and then add them to the customizer instead of the dashboard admin menu?

Join the discussion

Get more great content in your inbox

More articles

Delightful managed WordPress hosting

The #1 choice of over 70,000 digital creatives

Tour the platform
[if lte IE 8]
[if lte IE 8]