The Custom Background screen

The Custom Background screen is easy to add to any theme

Quick and simple way to add the new custom background selector to your WordPress 3.0 theme.


Seriously. That’s it. Just add that to the theme’s functions.php file.


Okay, so your theme does need to have the normal wp_head() call in it. For those of you more CSS inclined, this basically creates CSS code for the body and adds that code to the head output directly. Voila, your theme gets styled.

Note that you will need to also not define your own background stuff in the theme for this to work. If the user tries to put in a solid color background and you define an image background, then the color won’t work or be visible over your image. Best to not put anything background related onto the body at all, in fact.


For those more inclined to customize things, there’s actually three parameters you can use:

function add_custom_background($header_callback = '', $admin_header_callback = '', $admin_image_div_callback = '')

Each of these are references to a callback function. If you use them, then you need to define your own callback functions to replace the default ones.

The header_callback function is what builds and outputs the CSS. The function takes no parameters, but it can use get_background_image() and get_background_color() to retrieve the necessary information. From this information, the function should produce and output (echo) the necessary <style> block to show the image.

The admin_header_callback function is called in the head section of the admin side of things; in the Background section to be specific. The admin_image_div_callback is similar, called immediately after displaying “This is your current background” on that page, where the image is displayed. If used, the admin_image_div_callback replaces the display of the current background image, so you custom callback should produce that instead.

These two admin callbacks can be used to modify the Background admin page, to add custom text or information, etc.

But generally, most themes won’t need this level of customization. Just add the basic code to the theme and the defaults are good to go. 🙂



  1. I’m tempted to try placing this in a file in the mu-plugins folder on a site with a lot of blogs.. er… a network with a lot of sites… and see if ti shows up on all themes. 😀

    It should, so uber-cool if it actually works.

  2. yes, thanks, I have modify the Background

  3. Nice tip. Question-

    My theme calls a background image on the body tag. If I enable custom background and set a custom background COLOR, but not a custom background image, it does not override (disable) my theme’s background image.

    Is there a way to make it add a class to the body tag if a custom background or color is set? Using this additional class, I can disable my theme’s background image.

  4. […] For more information on using these custom callback functions, check out Otto on WordPress. […]

  5. […] bare nevne at jeg testet ut denne akkurat, add_custom_background(); – funket fin-fint. __________________ Tidligere nick: Grenland – […]

  6. Hello!

    Nice tutorial and explanation. Let’s suppose we don’t need this feature in our WP3 site using a child theme from Twenty Ten. How this function is disabled?

    Thank you!

  7. […] as they don’t need to touch the stylesheet anymore.WordPress 3.0 Custom Background SupportWordPress 3.0 Theme Tip: Custom Backgrounds3. Custom Post Type & Taxonomies:Besides menu management function, custom post type & […]

  8. Can anyone help me out?

    I’m using WordPress and I want to change the background of the footer i.e. by uploading background image from the backend. How can I do it?

    I tried using the add_custom_background() function but it changes the background of whole body. I want particularly for the footer.

    Thank you 🙂


  9. Life Saver! That wp_call() should be underlined because it’s very important. Without it, the add_custom_background is not going to do anything. Thank you very much for your post!

  10. Hey Otto,
    I know you are involved in WordPress development. It would be great to be able to set a default background image, like you can with custom header images.

    For header’s we have this:
    define( ‘HEADER_IMAGE’, ‘%s/images/logo.png’ );

    So why don’t we have this:
    define( ‘BACKGROUND_IMAGE’, ‘%s/images/background.png’ );

    Thanks for the tips!

  11. […] are already built into WordPress. Use the functionality that WordPress already supports, such as custom backgrounds, headers, post thumbnails and post formats. This is easier to implement because WordPress does all […]

  12. So simple to implement – thanks for that! Wondering though, is there a way to move the background color chooser to the same section as Background Image and rename it “Background”?

    I am using another section to control theme colors in general, and it is confusing to have multiple “Colors” sections.


  13. I need to upload many images on mys website but it take just one images. How can i custumise function to have many images. I an stater. Thank

Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Need to post PHP code? Wrap it in [php] and [/php] tags.