Trusted WordPress tutorials, when you need them most.
Beginner’s Guide to WordPress
25 Million+
Websites using our plugins
Years of WordPress experience
WordPress tutorials
by experts

What is: Custom Backgrounds

Editorial Note: We earn a commission from partner links on WPBeginner. Commissions do not affect our editors' opinions or evaluations. Learn more about Editorial Process.

Custom Backgrounds is a theme feature in WordPress which allows theme developers to enable support for background color and image customization. If custom backgrounds support is enabled in a theme, then the users can upload their own background images to use with the theme, or select a background color. The option to change background colors or change the background image is found under Appearance in the sidebar of WordPress Admin Panel.

Adding background image to your WordPress theme

The link to change or modify settings is titled Background and gives the option to upload a custom background image or color.

Users will also be able to see the live preview as they set the background image.

The feature can be added to themes and enabled by modifying the functions.php file. The process for doing this is shown below.

How to Add Custom Backgrounds Support to a WordPress Theme

To enable custom background support add the add_theme_support() function in your theme’s functions.php file with the following configuration.


$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 );

If you want to preset a default background image for a theme, then change the default-image option to add the location of the image you want to use.

Additional Reading

Editorial Staff

Editorial Staff at WPBeginner is a team of WordPress experts led by Syed Balkhi with over 16 years of experience in WordPress, Web Hosting, eCommerce, SEO, and Marketing. Started in 2009, WPBeginner is now the largest free WordPress resource site in the industry and is often referred to as the Wikipedia for WordPress.

The Ultimate WordPress Toolkit

Get FREE access to our toolkit - a collection of WordPress related products and resources that every professional should have!