How to add default custom background image WordPress 3.4?

custom background

At the moment I’m spending most of my time on the development of a base theme that I can use to build new sites for clients on. The reasons I have chosen to develop something in-house instead of using something that already is available are numerous and perhaps a topic for a different post in the future (or not).

One of the things I want this base theme to have is the ability to add a custom background image. As you can see in Twenty Ten and Twenty Eleven that is very easy to accomplish just by adding add_custom_background(); to the functions.php file.

And if you want your theme to have a default custom background then that is also not difficult to accomplish using the method of this excellent post by Chris Bavota.

However, this function will retire when WordPress 3.4 sees the light in May this year and be replaced by a new – more logical – function.

As it cost me an entire day to figure out how to add a default custom background image to WordPress 3.4 I thought it would be a good idea to post it here on WP TIPS.

From WordPress 3.4 onwards the function to include adding a custom background image in your theme will be:

add_theme_support( 'custom-background' );

The function also accepts a number of arguments add_theme_support( 'custom-background', $args ) and two of these arguments control the default custom background image and the default custom background color resp.:

add_theme_support( 'custom-background', array(
	// Background image default
	'default-image' => get_stylesheet_directory_uri() . '/images/bkgr.png',
	// Background color default, note to add it without the prefix of #
	'default-color' => 'ff9900'
) );

One thing to keep in mind when implementing this is that if you already have been playing around with the custom background image uploader, you will first need to click on the button that removes any previous uploaded images and restores the theme back to the default.

The credits for the code above go to Chip Bennett who wrote extensively about the custom backgrounds and custom headers in this article.

The person who helped me out at first however was Konstantin Kovshenin. After a day of looking for answers I contacted him via Twitter and he was so kind to immediately come up with this post. Thanks again Konstantin!