Custom Headers

Languages: English • Français • Hrvatski • Русский • Headers 日本語 Português do Brasil • 中文(简体) • (Add your language)

Custom Header is a theme feature introduced with Version 2.1. Custom header is an image that is chosen as the representative image in the theme top header section.

Adding Theme Support

Since Version 3.4, themes need to use add_theme_support() in the functions.php file to support custom headers, like so:

add_theme_support( 'custom-header' );

Note that you can add default arguments using:

$defaults = array(
	'default-image'          => '',
	'width'                  => 0,
	'height'                 => 0,
	'flex-height'            => false,
	'flex-width'             => false,
	'uploads'                => true,
	'random-default'         => false,
	'header-text'            => true,
	'default-text-color'     => '',
	'wp-head-callback'       => '',
	'admin-head-callback'    => '',
	'admin-preview-callback' => '',
);
add_theme_support( 'custom-header', $defaults );

You must also register the header image before it can be used as a default in your theme.

Example

Set a custom header image

Set a default header image 980px width and 60px height:

$args = array(
	'width'         => 980,
	'height'        => 60,
	'default-image' => get_template_directory_uri() . '/images/header.jpg',
);
add_theme_support( 'custom-header', $args );

Upload other custom header images

Set a default header image and allow the site owner to upload other images:

$args = array(
	'width'         => 980,
	'height'        => 60,
	'default-image' => get_template_directory_uri() . '/images/header.jpg',
	'uploads'       => true,
);
add_theme_support( 'custom-header', $args );

Use flexible headers

Set flexible headers:

$args = array(
	'flex-width'    => true,
	'width'         => 980,
	'flex-height'    => true,
	'height'        => 200,
	'default-image' => get_template_directory_uri() . '/images/header.jpg',
);
add_theme_support( 'custom-header', $args );

update your header.php file to:

<img src="<?php header_image(); ?>" height="<?php echo get_custom_header()->height; ?>" width="<?php echo get_custom_header()->width; ?>" alt="" />

Backwards Compatibility

To add backwards compatibility for older versions, use the following code:

global $wp_version;
if ( version_compare( $wp_version, '3.4', '>=' ) ) :
	add_theme_support( 'custom-header' );
else :
	add_custom_image_header( $wp_head_callback, $admin_head_callback );
endif;

Resources

WordPress Theme Support Generator

Theme Support: add_theme_support(), remove_theme_support(), current_theme_supports()
Theme Features: sidebar, menus, post-formats, title-tag, custom-background, custom-header, custom-logo, post-thumbnails, automatic-feed-links, html5, editor-style, content_width

Function: header_image
Function: get_header_image
Function: get_custom_header

WordPress.org

Codex