Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/register default headers


Register a selection of default headers to be displayed by the custom header admin UI.

The parameter $headers is required, to merge with already registered headers.

Note: This function is needed in order to use custom headers. The header image(s) must first be registered before using it.


<?php register_default_headers$headers ); ?>


(array) (required) Array of headers keyed by a string id. The ids point to arrays containing 'url', 'thumbnail_url', and 'description' keys.
Default: None

Return Values

This function does not return a value.


Edit the file functions.php inside your theme and add the following code, replacing the images and descriptions where required.

The %s is replaced with your themes path, so place the images in your theme directory.

register_default_headers( array(
	'wheel' => array(
		'url'           => '%s/images/headers/wheel.jpg',
		'thumbnail_url' => '%s/images/headers/wheel-thumbnail.jpg',
		'description'   => __( 'Wheel', 'twentyeleven' )
	'shore' => array(
		'url'           => '%s/images/headers/shore.jpg',
		'thumbnail_url' => '%s/images/headers/shore-thumbnail.jpg',
		'description'   => __( 'Shore', 'twentyeleven' )
	'trolley' => array(
		'url'           => '%s/images/headers/trolley.jpg',
		'thumbnail_url' => '%s/images/headers/trolley-thumbnail.jpg',
		'description'   => __( 'Trolley', 'twentyeleven' )
) );

Note: The code above was lifted from the TwentyEleven theme files.

To reference a image in a child theme (ie in the stylesheet directory), use %2$s instead of %s.

register_default_headers( array(
	'child' => array(
		'url'           => '%2$s/images/headers/child.jpg',
		'thumbnail_url' => '%2$s/images/headers/child-thumbnail.jpg',
		'description'   => __( 'Child', 'twentyeleven' )
) );

Change Log

Since: 3.0.0

Source File

register_default_headers() is located in wp-includes/theme.php.


Custom Headers: add_custom_image_header(), remove_custom_image_header(), register_default_headers(), unregister_default_headers()

See also index of Function Reference and index of Template Tags.