WordPress Custom Header theme feature

Introduced in WordPress Version 2.1, the WordPress custom header is a theme feature that allows for a user to select a representative image that appears, typically, at the top section of a theme/site.

While the featured image is an ambassador or representative of a specific entry, the header image is more of a site-wide representative. It visually indicates to the visitor what they expect to see/read within the site or is simply a random visual accompaniment to the content.

To simply allow for your theme to use this future, add the following to the functions.php:

add_theme_support( 'custom-header' );

Typically, you’ll want a little more control over this feature beyond just making it available. For instance, you might want to set a default image to be used when a user doesn’t upload and specify a custom header image. You might also want control over width and height. Luckily this function accepts several arguments.

Defining the function

Let’s say we want a image that’s no wider than 960px. We’d also like to set a default height of 100px but as long as the width stays below 960, the height can be whatever (relative to the set width, anyway). Also, we’d like to set the default header image to our beautiful default-sunset-header.jpg file that’s already in the images/ folder within the theme directory. In addition, we’d like to allow the user to upload their own image to replace the default.

To accomplish this, we would then adjust the above add_theme_support() function to look like this:

add_theme_support( 'custom-header', array (
  'width'             => 960,
  'height'            => 100,
  'flex-height'        => true,
  'default-image'     => get_template_directory_uri() . '/images/default-sunset-header.jpg',
  'uploads'           => true

Using the function

To simply output the header, we use the header_image function. Given that the width and height were explicitly set, adding those values to the <img> tag might be necessary.

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

Depending on how you use this feature, you might want/need to wrap the output in a link that links to the home URL. In addition, you might need to check that the header image actually exists before outputting the above markup.

To check if the header image exists and wrap it in a home_url link, replace the above with the following:

<?php if ( get_header_image() ) : ?>
  <a href="<?php echo esc_url( home_url( '/' ) ); ?>">
    <img src="<?php header_image(); ?>" width="<?php echo get_custom_header()->width; ?>" height="<?php echo get_custom_header()->height; ?>">
<?php endif; ?>

This is the typical approach that WordPress takes to theme features:

  1. first you allow use of them via your theme’s functions.php then,
  2. in the view templates, you do a conditional check to see if the theme’s user has used the defined feature and if they have,
  3. you then output whatever it is that they, well, input.

A bit convoluted but pretty intuitive: Define, check and then output.