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

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.

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 )
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.
Thanks!
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.
Bruno Kos
September 23, 2016
Who is this Puneet? I am sure I've heard of him before :)
Eric
February 3, 2016
thanks!
needed this
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!
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.
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.
Narinder kumar
April 6, 2017
Thanks for sharing great customization feature you can share with us.
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.
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.
Tem
July 29, 2017
Thank you! This article helps me!
Rahman
October 16, 2017
Thank you so much for your tutorial. It's very helpful article.
Thanks again
Ryan
November 4, 2017
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
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.
Chalo
March 13, 2018
Very Helpful, thank you for publishing this tutorial, excellent!
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?
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.