WordPress Custom Backgrounds theme feature

The WordPress custom backgrounds theme feature allows for the customization of the theme’s background image and color. If a specific background image and color have already been set by the theme, the custom background feature can, through the WordPress-provided UI, allow the user to adjust them accordingly.

Add Theme Support

Similar to custom header, to make available and allow use of this feature in your theme, you simply need to invoke the add_theme_support() function in your theme’s functions.php. Like so:

add_theme_support( 'custom-background' );

With that in place, WordPress gives you an added link and screen labeled “Background” under the primary “Appearances” menu from which you’re able to manipulate the background image and color.

Naturally, as with such features, you’ll need a little more granular control. Specifically, given what this feature affords, you can understand it by think of it as a CSS “background” declaration. You’ll, at a minimum, want to define a background image and a background color.

You’d obviously allow this feature with the implicit understanding that the theme’s end user could and likely will change your default settings. Your theme’s end user can decide what wild variations to your gestalt theme they’d like to apply.

Having already added support for this feature, lets go ahead and set defaults for the background image and color. Revise the above function to look like this:

add_theme_support( 'custom-background', array (
  'default-color' => 'f6f6f6',
  'default-image' => get_template_directory_uri() . '/images/default-bg-image.png',

Once you invoke the function, WordPress will automatically print an embedded stylesheet in the <head> to take care of the background CSS declarations. You just need to make sure than in your <body> element you’re using the body_class() i.e. at a minimum, your opening body class needs to look like this:

<body <?php body_class(); ?>>

With the body_class() in place, WordPress appends the necessary CSS classes to the body element that will allow targeting of the background for styling. e.g. when a background image is used, WordPress adds a “custom-background” CSS class to the body element.

In addition, to allow WordPress to output the requisite embedded stylesheet, you need to have <?php wp_head(); ?> in place right before the close of your <head> tag.