If you’re a theme developer and like to use WordPress’ add_custom_background() function in your themes, you’ve probably noticed a small problem before with the way this is handled. If you haven’t noticed, you may be in for a surprise after reading this tutorial and testing your theme.

The “bug” occurs when you define a custom background image in your theme’s style.css file but also add support for WordPress’ native custom background feature. If the user just wants to use a background color (but not an image), your theme’s background in style.css will hide the the user’s selected background color.

This tutorial will walk you through the issue and how to fix it for your theme.

Spotting the background issue

Let’s assume you have some CSS defined in your theme that adds a custom, repeating background image to the body element in your theme. Your code would look something like the following.

body {
	background: #f7f7f7 url(images/bg-body.png) repeat 0 0;
	}

Your theme’s display would look something like the following screenshot.

So far, everything should be in working order for your theme.

Now, let’s suppose you added a call to add_custom_background() in your theme’s functions.php file. This feature will allow theme users to add a custom background color and/or background image. The background image functionality should work perfectly with your theme. The problem is when a user selects only a custom background color as shown in the next screenshot.

When the user views their site, they will not see their selected background color. They will still see your theme’s background image. This is because WordPress will only add CSS for background-color rather than background. Thus, the background image defined in style.css hides the background color.

There are pros and cons to WordPress handling the custom background feature this way. And, the workaround for this problem is pretty easy.

The custom background fix

Most theme developers simply drop the following line of code in their theme’s functions.php file.

add_custom_background();

Many of them don’t know about the parameters for the add_custom_background() function:

add_custom_background( $header_callback, $admin_header_callback, $admin_image_div_callback );

The parameter we’re concerned about for this tutorial is the $header_callback parameter. It allows you to define a custom function that will be used to display the <style> output in the theme header, overwriting what WordPress would normally output.

To use this functionality, you ned to replace your call to add_custom_background() in your theme’s functions.php file with the following line of code.

add_custom_background( 'my_custom_background_callback' );

Then you need to add your custom callback function to functions.php. The following code will do a couple of things:

• Check if there’s a background image and default to the WordPress output if one is found.
• Use background instead of background-color when a user defines a custom background color but not a custom background image.

function my_custom_background_callback() {

	/* Get the background image. */
	$image = get_background_image();

	/* If there's an image, just call the normal WordPress callback. We won't do anything here. */
	if ( !empty( $image ) ) {
		_custom_background_cb();
		return;
	}

	/* Get the background color. */
	$color = get_background_color();

	/* If no background color, return. */
	if ( empty( $color ) )
		return;

	/* Use 'background' instead of 'background-color'. */
	$style = "background: #{$color};";

?>
<style type="text/css">body { <?php echo trim( $style ); ?> }</style>
<?php

}

Fix those backgrounds

I can’t tell you how many times I’ve had to point out to theme developers when reviewing their themes that the user-selected background color is hidden by the theme’s background image. The above code will solve this issue.

There are other methods for doing this, but I’ve found that this method allows for a lot of flexibility and puts me, the theme developer, back in control of the output.