How to add options to the WordPress Customizer

Krissie VandeNoord's Layout avatar

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, 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


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.


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
// Add a control to upload the logo
$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'your_theme_logo',
'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.


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:

// 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.


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-&gt;add_section('your_theme_footer', array(
'title' =&gt; 'Footer',
'description' =&gt; '',
'priority' =&gt; 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.

What’s next?

Don’t try this on your live site! Try out Local! Learn more here.

Comments ( 14 )

  1. Dariusz

    June 13, 2020

    Hi. Thanks for post. Used some informations for my website. Just a information for you that your codes are broken on website - they are converting => symbols in to unicode breaking code. This is due to changes in Wordpress and plugin that you using is not compatible with that. Have this issue on my website and decided to disable it and use build in code block in wordpress gutenberg.

  2. Andrew

    October 31, 2018

    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?

  3. Chalo

    March 13, 2018

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

  4. Ryan

    November 4, 2017


    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?


    • Ryan

      November 4, 2017

      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.

  5. Rahman

    October 16, 2017

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

    Thanks again

  6. Tem

    July 29, 2017

    Thank you! This article helps me!

  7. Noor Ullah

    July 23, 2017

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

  8. Rushax

    July 19, 2017

    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.

  9. Narinder kumar

    April 6, 2017

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

  10. Dario

    March 17, 2017

    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.

  11. Maarten Belmans

    November 19, 2016

    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.

  12. Eric Njanga

    July 28, 2016

    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!

  13. Eric

    February 3, 2016

    needed this

  14. Puneet Sahalot

    January 25, 2016

    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.


    • Bruno Kos

      September 23, 2016

      Who is this Puneet? I am sure I've heard of him before :)

    • Krissie

      January 25, 2016

      Thanks Puneet, that's a great point! I was trying to give the simplest of examples, but it is good practice to use esc_url for sure.

Join the discussion