Notice: get_settings is deprecated since version 2.1.0! Use get_option() instead. in /var/www/vhost/ on line 3840 Notice: get_settings is deprecated since version 2.1.0! Use get_option() instead. in /var/www/vhost/ on line 3840

WordPress 3.4 introduced a new method of dealing with custom headers and backgrounds. The old functions add_custom_image_header( $args ) and add_custom_background( $args ) were depreciated in favor of add_theme_support( 'custom-header', $args ) and add_theme_support( 'custom-background', $args ). While these new functions are pretty similar to their predecessors, there is still a good bit of information about working with them that is not on the codex (or anywhere else I looked). So here are some helpful tips when working with custom headers and backgrounds.


If you’re writing any kind of callback that involves data from a custom header or background, there are some functions that can really help you. These functions are all basically aliases for the get_theme_mods() function. You can take a look at the available data for yourself by var_dumping it on your theme.

var_dump( get_theme_mods(); 

Since keys will only appear once something has been changed, the structure of the array returned by get_theme_mods() will depend on what modifications have been made. Dumping my newest theme, for example:

$returned = array(
	'header_textcolor' => '333333',
	'background_color' => 'eee',
	'nav_menu_locations' => array( 'primary-menu' => 3 ),
	'header_image' => '',
	'header_image_data' => array(
		'url' => '',
		'thumbnail_url' => '',
		'description' => 'bitLumen icon only, no logo text' )

As you can see, all the data you’d ever need for styling a theme with a custom header or background is available using get_theme_mods(), but you should used the aliased functions whenever available for maximum forward and backward compatibility.

Finding Particular Data

The following methods are available to retrieve specific data about your theme’s current custom background or header:

Custom Header Image

Use the following functions to find the header image locations and size:

// image location
	$header_url = get_custom_header()->url;
	$header_url = get_header_image();
	$header_thumbnail_url = get_header_image()->thumbnail_url;
// image size
	$header_width = get_custom_header()->width;
	$header_height = get_custom_header()->height;

Custom Header Text

Use the following functions to find if the header text should be displayed and if so what color:

$show_header_text_or_not = display_header_text();
$header_textcolor = get_header_textcolor(); 
	/* false if disabled, or 'blank' if header text is enabled 
	   but currently opted not to be displayed. */

Background Images

Use the following functions to find the position, size, repeat, and url of the background image.

	$background_image_url = get_background_image();
	$repeat = get_theme_mod( 'background_repeat', 'repeat' ); // defaults to repeat
	$position_x = get_theme_mod( 'background_position_x', 'left' ); // defaults to left
	$attachment = get_theme_mod( 'background_attachment', 'scroll' ); // defaults to scroll

Background Color

Get the custom background color.

$bg_color = get_background_color();

Dynamic Style Sheets

This should be all the data you need to style your theme or create customized callback functions. But these are mostly CSS values, so how do you translate from PHP to CSS? The easy answer is just to print style information using PHP like so:

echo '<html style="background-color:#' . get_background_color() . ';">'

But this is bad coding. You should never use the style=”” html tag, and always use properly enqueued style sheets. But how can you use a style sheet with dynamic PHP variables? Just fake it! Make a PHP file that sends CSS headers. Save this file as style.php:

<?php header( 'Content-type: text/css' ); 
if( array_key_exists( 'bg_color', $_GET&#91;'bg_color'&#93; ) )
	$bg_color = $_GET&#91;'bg_color'&#93;;
else $bg_color = 'ffffff'; ?>
This file will be read as a CSS style sheet but you
can insert values using PHP!

html {
	background-color:#<?php echo $bg_color; ?>;

Notice there is a $bg_color variable that we need to provide externally. Because WordPress loads the stylesheets before the core, you won’t be able to use any WordPress functions in the style.php file. But you can still access them by piping them in through $_GET. So we would queue the style sheet with the query variables included like so:

wp_enqueue_style( 'slug-dynamic', get_stylesheet_directory_uri() . '/style.php?bg_color=' . get_background_color() );

If you have a lot of variables to pass, just serialize them into a string, urlencode it, pass it through, then urldecode, unserialize, and extract.

This should be everything you need to properly style themes using custom header and backgrounds.

Leave a Reply

Your email address will not be published. Required fields are marked *

Post Navigation