WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Custom Backgrounds

Custom Backgrounds is a theme feature that provides for customization of the background color and image.

See also Appearance Background Screen.

Adding Theme Support

Since Version 3.4, themes need to use add_theme_support() in the functions.php file to support custom backgrounds, like so:

add_theme_support( 'custom-background' );

Note that you can add default arguments using:

$defaults = array(
	'default-color'          => '',
	'default-image'          => '',
	'default-repeat'         => '',
	'default-position-x'     => '',
	'default-attachment'     => '',
	'wp-head-callback'       => '_custom_background_cb',
	'admin-head-callback'    => '',
	'admin-preview-callback' => ''
);
add_theme_support( 'custom-background', $defaults );

Example

An example using default '#000000' background color with 'background.jpg' background image:

$args = array(
	'default-color' => '000000',
	'default-image' => '%1$s/images/background.jpg',
);
add_theme_support( 'custom-background', $args );

Outcome

The purpose of this call to add_theme_support() is to enable the Custom Background screen in the administrator's Appearance menu. It also serves as a declaration that the theme has properly implemented the body_class() and wp_head() template tags to provide feature compatibility.

When the administrator sets custom values for the theme, WordPress generates an extra style sheet in-line with the HTML headers, usually right before the end of the document's HEAD element. The extra style sheet overrides the background values from the theme's style sheet.

Example output:

<style type="text/css" id="custom-background-css">
body.custom-background { background-color: #bdd96e; }
</style>

Note that setting the default-image parameter will instantly cause that value to become the effective Custom Background, whereas setting the default-color has no effect until the administrator visits the Custom Background page. To override this default behavior, you would have to provide a replacement for the _custom_background_cb() function.

Backwards Compatibility

To add backwards compatibility for older versions, use the following code:

global $wp_version;
if ( version_compare( $wp_version, '3.4', '>=' ) ) :
	add_theme_support( 'custom-background' ); 
else :
	add_custom_background( $args );
endif;

Note: As we're now beyond the release WordPress 3.6, providing backwards compatibility for any version prior to 3.4 will be a violation of the Theme Review guidelines.

Resources

Related

Theme Support: add_theme_support(), remove_theme_support(), current_theme_supports()
Features: sidebar, menus, post-formats, title-tag, custom-background, custom-header, post-thumbnails, automatic-feed-links, html5, editor-style, content_width