WordPress Theme Customizer: Add header background-image CSS using inline styles.

Wordpress Theme Customier Background Image Control

Avatar for Ben Kaminski  

October 14th, 2014


If you’re a WordPress theme developer such as myself, I’m sure you’re becoming familiar with the theme customizer. I’m not an honest to goodness php programmer, but I know enough to get myself in trouble — or in this case — figure out something worth talking about.

If you have visited the WordPress Codex “Theme Customization API” page, there’s a ton of information on setting up the customizer and using it in your theme. Although, with regard to documentation for uploading a background image to be used in the header of your site via the theme customizer, well… there’s not much to be found. See image underneath title.

So taking bits and pieces from tutorials and the Codex, I was able to craft something that worked for me in my scenario. My scenario being, I wanted my WordPress user to be able to upload and change the header background image by using the theme customizer. This image is the entire width of the page and about 400px tall. Being that we live in a responsive internet now, it was also necessary that this image respond with the page. Side-note: The responsiveness of my background image is more for larger screens as I wanted to maintain a fixed height but after a certain width, wanted the picture to expand rather than leave whitespace. Follow me?

Anyhow, back to the important aspect of getting this task completed. I was able to find a great tutorial on some basic usage and functionality of the WordPress Theme Customizer. The tutorial taught me how to upload an image using the customizer but, and this is a big BUT!!! This tutorial showed how to place the image on the page… not really a CSS background-image property that I was looking for here. I definitely needed my image to be a CSS background not an in page “img src”. But what the php was doing here was simply outputting the url to the newly uploaded image, so I thought to myself… I’m already capturing the image URL, what can I do with it to make it a CSS “image-background”? You can’t simply embed php within CSS… can you?

Assuming that you can’t, I thought to myself again… if I take this background-image url and place it in some inline CSS could it work? Of course it would! Whether or not you’re a fan of inline CSS, this will work for you allowing you full CSS control over your newly uploaded background image. Keep in mind as well, I had this section pre-designed with the background image included via static means. I just wanted to convert what I had already in place over and make it dynamic.

Get to work people!

Open up your “functions.php” file in your WordPress theme and paste in the following code.

Obviously you’re going to have to make some changes where I put “your_themename”, or not… It’s really up to you. It will work either way. With that being said, I’m going to assume the “your_themename” as the nomenclature going forward in this tutorial.

Theme Customizer Upload Background ImageAnyhow, what the above code snippet that we just added to our functions.php file actually does is three things. First it adds the section to the theme customizer in WordPress. The above code will produce a theme customizer section with the name of “Header Background”. In the second part, it adds the setting for the image being uploaded and in the third section it adds the controls to the theme customizer. In this case, an image uploader. If all goes as planned, you should see something that resembles the image on the left (or on top depending on the device you’re using) in your theme customizer now.

Notice I changed the text in the “add_section” description? I did this to notate to the end user what the image dimensions and file-size should be. You can use that section to communicate any message to the user that you would like.

Either way, now that we have added the above snippet, we are now able to upload an image into the theme customizer, which in-turn, places the image in the Media Gallery on the WordPress dashboard. But, that’s not the point of this tutorial! We want to take this newly uploaded image and place it as a CSS background-image.

Some HTML and CSS with a dash of PHP

First I’m going to show you my basic layout. This is the layout before any dynamics were added to it. AKA, the static version.


In this code, I had the background image set up in my css ID “header-photo-area” as such:

Then I have a custom widget area on top of it, but that’s not whats necessary here. What’s necessary is taking a generated php string (or url) and making it a useable CSS image background.

What I decided to do (remember when I mentioned inline styles earlier?) was to simply take the “background-image” attribute and make an inline style out of it attached to the “header-photo-area” ID! Then removing the attribute from the CSS. Here’s how I accomplished it:

And my CSS without the background-image attribute:

The Conclusion

Because I knew that the theme customizer was working and actually uploading an image as well as producing the url to said image, I realized that I could simply use an inline style to accomplish this task by inserting the call to the custom function as the url for the inline “background-image” style. I realize this is more of a work-around than an actual solution, but considering the options out there of using the WordPress theme customizer to handle background images goes, this was the best I could come up with.

As always, I hope you found this tutorial useful and hopefully it sparked some ideas for you. I always look forward to your comments so feel free to leave them at will!

Leave a Comment Below...

Your email address will not be published.

Related: , , , , , , ,

Footer Meta:

Copyright © 2009 - 2017 benkaminski.com