Software, Development, and WordPress

Maintainability of WordPress Theme Customizer Code

When working with the WordPress Theme Customizer, one of the things you may find yourself doing is writing out inline styles into one of the templates for your theme. Most likely, this will happen within the context of your header template since that’s where most of your styles and JavaScript sources are included.

Sure, it’s possible to handle a lot of the work via JavaScript and to use separate stylesheets to handle the general styles, but if you’re looking to set something up like, say, backgrounds that can be selected via the Theme Customizer, then you’re going to need to write out inline styles.

And if you’re in the habit of keeping your code separated such as styles reside in CSS files, behavior functionality resides in JavaScript files, and templates hold markup and PHP, then this can be a little bit annoying. It breaks the trend, you know?

There is somewhat of a solution to this, though.

Whenever I’ m working with the Theme Customizer, I make sure to do several things:

  1. Have a JavaScript file solely dedicated to working with the Theme Customizer API. I don’t want to mix that logic in with anything else as it’s got a single purpose that I don’t want cluttered with other code. I’ll combine it into a single script later, but during development, I will have a `theme-customizer.js`.
  2. Have a `theme-customizer.php` file that’s responsible or defining and setting up all of the functionality specficially for the theme and its relationship to the customizer. Here, all of the sections, settings, and other features are defined but nothing else. Like the JavaScript file, this file is used solely to integrate the customizer into the theme.

In addition to those two files, I also maintain a template part (or partial, as some refer to it), that I normally call customizer.php. The file may look something like this:

As you can tell from the code, the file is responsible for checking the values of the theme modifications via the WordPress API and then updating them accordingly via inline styles.

Though we can’t write this out directly into a separate CSS file (which would be ideal), we can write it out into a separate file that helps with maintainability throughout the course of a theme’s lifetime. Then, once it’s defined, you can easily include it in the header template with the following line (just after the wp_head):

It’s simple, sure, but things like this can go along way into making it much easier to keep your code logically separated into cohesive components that can be easily developed and maintained over time.


  1. Luis Rock

    Hi, Tom.

    Is there any difference using the “get_template_part()” before “wp_head()” ?

    I always end the with “wp_head()” and I was wondering if it is only a superstition that I have…


    • Tom

      It’d really depend on what’s being written out via the get_template_part. Ending with wp_head is not a bad practice :).

  2. Devin Price

    Inspired by the Make Theme (by Theme Foundry), I started using a style builder ( But I totally agree about separating out all that logic into its own file. I generally use “styles.php”.

  3. webweaverman

  4. Fyn

    Very helpful indeed :)

  5. Timothy Brand (@brandgraphics)

    I have to admit this is why I never used the theme customizer with any themes I’ve built. I like the concept but I feel like from a development standpoint it was always a pain to keep things separated. This definitely helps solves that issue. Thank you.

    • Tom

      Personally, I’m a huge fan of the customizer – not so much of options in the dashboard.

      I think it closes the gap between what the user expects to happen and what really happens because they can see the changes in real time.

      Still, though, it’s not without it’s organizational challenges (hence this post :).

  6. Ted

    I’ve been digging through and trying to decipher Themify’s customized customizer in attempt to learn how to implement some of the functionality. It really amazing what they’ve done. If you haven’t already, download their Basic theme (it’s the free one) and take a look at it.

    I’m also quite impressed with Kirki Framework ( ), which arisath has been pretty active with further developing it, lately.

    With all the changes to WordPress over the past couple of years, I think the customizer is the one development that took WordPress to a whole nother level.

    • Tom

      With all the changes to WordPress over the past couple of years, I think the customizer is the one development that took WordPress to a whole nother level.

      Agreed. I think it has potential to be abused (like anything), but I really like the work that has been done and that has come with it thus far.

  7. Ulises

    Thanks for the article Tom. I have a question. I am working locally with MAMP. I went ahead and created a customizer-styles.php and threw in there a callback function for my custom-header image styles.

    I called the function from my theme-customizer.php like this:

    include ‘customizer-styles.php’;


    and it worked fine, but the problem is if I log out from my WP admin, by the time I try to log in again I get a blank page, I can’t acces my Admin, all its gone.

    Then when I check MAMP for log errors I get this:

    PHP Warning: Cannot modify header information – headers already sent by (output started at /Applications/MAMP/htdocs/Namaste-Theme/wp-content/themes/Namaste/partials.php:9) in /Applications/MAMP/htdocs/Namaste-Theme/wp-includes/pluggable.php on line 1228

    Do you have any idea of why this occurs? thank you in advance and great article!

    • Tom

      include ‘customizer-styles.php’;

      This line looks fine.


      This may be problematic depending on what’s contained in the function.

      PHP Warning: Cannot modify header information – headers already sent by (output started at /Applications/MAMP/htdocs/Namaste-Theme/wp-content/themes/Namaste/partials.php:9) in /Applications/MAMP/htdocs/Namaste-Theme/wp-includes/pluggable.php on line 1228

      This is actually saying the problem exists in your partials.php file and has nothing to do with your Theme Customizer. Whatever is on line 9 of your partials file is causing the problem, based on what this warning is showing.

  8. Ido

    Hi Tom, I liked your article.

    I’m working a lot with the customizer my self and usually for styles I use the wp_head hook to load the styles.

    I was wondering is there a benefit for using get_template_part?


    • Tom

      I use get_template_part for modularity and re-use.

      That is, if I have part of a template I want to use elsewhere in a theme or plugin, then I abstract it into its own file and I can call it once anywhere else in the code.

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑