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

Function Reference/add custom image header

This function has been deprecated. That means it has been replaced by a new function or is no longer supported, and may be removed from future versions. All code that uses this function should be converted to use its replacement if one exists. See also wp-includes/deprecated.php. Use any of these functions instead.


Add callbacks for image header display.

The parameter $header_callback callback will be required to display the content for the 'wp_head' action. The parameter $admin_header_callback callback will be added to Custom_Image_Header class and that will be added to the 'admin_menu' action.

Replace With

add_theme_support( 'custom-header' )


<?php add_custom_image_header$header_callback$admin_header_callback$admin_image_div_callback ?>


(callback) (required) Call on 'wp_head' action.
Default: None
(callback) (required) Call on custom header administration screen.
Default: None
(callback) (required) Output a custom header image div on the custom header administration screen. Optional.
Default: None

Return Values

This function does not return a value.


Edit the file functions.php inside your theme and add the following code.

Four constants must be defined in order for the custom image header to work:

define('HEADER_TEXTCOLOR', 'ffffff');
define('HEADER_IMAGE', '%s/images/default_header.jpg'); // %s is the template dir uri
define('HEADER_IMAGE_WIDTH', 775); // use width and height appropriate for your theme
define('HEADER_IMAGE_HEIGHT', 200);

If you don't want to allow changing the header text color, add:

define('NO_HEADER_TEXT', true );

Then change the first definition to:

define('HEADER_TEXTCOLOR', '');

If you intend to create child themes use:

define('HEADER_IMAGE', trailingslashit( get_stylesheet_directory_uri() ).'images/banner.jpg');

Otherwise, you'll pick up the header image for the parent theme rather than the child.

Next you need to write two functions. One will be included in the site header. The second will be included in the admin header. Both of these functions are required. The smallest possible amount of code would be something like this, although you can do anything you need.

// gets included in the site header
function header_style() {
    ?><style type="text/css">
        #header {
            background: url(<?php header_image(); ?>);
// gets included in the admin header
function admin_header_style() {
    ?><style type="text/css">
        #headimg {
            width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
            height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
            background: no-repeat;

Finish with calling the add_custom_image_header function with the two earlier function names as parameters:

add_custom_image_header('header_style', 'admin_header_style');

Taking this last step will make the Custom Header item appear in the Appearance menu. WordPress takes care of everything else.


Change Log

Source File

add_custom_image_header() 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.