How to Set Default CSS Background Properties in WordPress Themes

Here’s a handy trick for WordPress theme developers. As of WordPress 3.8, theme authors have the ability to customize defaults when adding custom background support. For example, you can set a default for any of the following CSS background properties:

  • background-color
  • background-image
  • background-repeat
  • background-attachment
  • background-position

Oftentimes users want their sites to look similar to the demo, but they may be unaware of how to adjust the background properties to achieve that. It’s nice to have some defaults in place so that the theme looks similar to the demo right out of the box, without any adjustments.

Depending on the background image that you select, it can be advantageous to set its defaults to the most sensible display for that image. For example, if your default background is an image that’s meant to tile, you want it displayed like that after the user activates the theme.

Adding custom background support to the customizer is done through your theme’s functions.php file:

[php light=”true”]add_theme_support( ‘custom-background’ );[/php]

From here you can further customize the background properties by adding default arguments. Usually themes add custom background support to a setup function with other customizer options. Here’s a quick example of setting a default background to no-repeat, centered position with fixed attachment.

[php]function yourtheme_setup() {
‘default-color’ => ‘2d2d2d’,
‘default-image’ => get_template_directory_uri() . ‘/images/background.jpg’,
‘default-repeat’ => ‘no-repeat’,
‘default-position-x’ => ‘center’,
‘default-attachment’ => ‘fixed’,

add_action( ‘after_setup_theme’, ‘yourtheme_setup’ );

Here’s what that looks like in the customizer by default after the user installs the new theme:


Of course, the user can still adjust these properties through the customizer to suit their own custom background images. The defaults simply ensure that the packaged background image looks nice when the theme is activated for the first time.


2 responses to “How to Set Default CSS Background Properties in WordPress Themes”

  1. After scratching my head at this for awhile …

    We are talking here about the Admin Theme Options that allow tweaking of theme elements, through the (relatively standardized?) Dashboard UI? Which the theme developer provided for, in the ‘guts’?

    I’m still fuzzy, how it comes to be that we are left in the lurch on the defaults, in the first place. I’ve installed a lot of themes – and then tweak them – and I don’t notice issues with … ‘omg – how come this thing doesn’t look like the picture on the box’!

    Interesting post … but did I come in halfway through the lecture? ;)

    • If you ship a theme with a default background included, it’s just nice to have it in the right positioning when it’s activated. I did this recently for a theme I released because I didn’t want the user to have to worry about positioning the background.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.