Adding a custom header image to your WordPress theme

Every new iteration of WordPress (version 3.0.1 at the time of writing) brings a host of new features and bug fixes. One feature that I completely missed in 3.0 was the new custom header functionality. Before 3.0 it would be a case of hacking together your own solution using custom fields or using a separate plug-in. Thankfully the WordPress team have added this functionality directly to the core.

It just so happens that I’ve had a request for a customisable header image on an future project, so decided to have a play and see how difficult it is to implement. Well it isn’t difficult at all, very simple in fact.

First you will need to edit your functions.php located in your theme directory. Go ahead and create one if it isn’t in the directory. Now copy and paste the code below into the file. I’ve commented the code but it’s all quite self explanatory. Change the height and width of the image and change the directories where needed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<?php
//Check see if the customisetheme_setup exists
if ( !function_exists('customisetheme_setup') ):
    //Any theme customisations contained in this function
    function customisetheme_setup() {
        //Define default header image
        define( 'HEADER_IMAGE', '%s/header/default.jpg' );
       
        //Define the width and height of our header image
        define( 'HEADER_IMAGE_WIDTH', apply_filters( 'customisetheme_header_image_width', 960 ) );
        define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'customisetheme_header_image_height', 220 ) );
       
        //Turn off text inside the header image
        define( 'NO_HEADER_TEXT', true );
       
        //Don't forget this, it adds the functionality to the admin menu
        add_custom_image_header( '', 'customisetheme_admin_header_style' );
       
        //Set some custom header images, add as many as you like
        //%s is a placeholder for your theme directory
        $customHeaders = array (
                //Image 1
                'perfectbeach' => array (
                'url' => '%s/header/default.jpg',
                'thumbnail_url' => '%s/header/thumbnails/pb-thumbnail.jpg',
                'description' => __( 'Perfect Beach', 'customisetheme' )
            ),
                //Image 2
                'tiger' => array (
                'url' => '%s/header/tiger.jpg',
                'thumbnail_url' => '%s/header/thumbnails/tiger-thumbnail.jpg',
                'description' => __( 'Tiger', 'customisetheme' )
            ),
                //Image 3
                'lunar' => array (
                'url' => '%s/header/lunar.jpg',
                'thumbnail_url' => '%s/header/thumbnails/lunar-thumbnail.jpg',
                'description' => __( 'Lunar', 'customisetheme' )
            )
        );
        //Register the images with Wordpress
        register_default_headers($customHeaders);
    }
endif;

if ( ! function_exists( 'customisetheme_admin_header_style' ) ) :
    //Function fired and inline styles added to the admin panel
    //Customise as required
    function customisetheme_admin_header_style() {
    ?>
        <style type="text/css">
            #wpbody-content #headimg {
                height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
                width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
                border: 1px solid #333;
            }
        </style>
    <?php
    }
endif;

//Execute our custom theme functionality
add_action( 'after_setup_theme', 'customisetheme_setup' );
?>

By adding the code above you will now see a new option under “Appearance” in the admin panel called “Header”. From there you should be able to see all the images and options we just set in the functions.php file. The only thing left to do now is add the header image to the theme.

Where you place the following code will be depend on your theme setup; I’ve decided to place it in the header.php file as I want the image to appear on every page. You may only want the image to appear on specific templates e.g. pages, archive, category (you could also use WordPress conditional tags to do this).

1
2
3
4
5
6
<div id="header">
    <!-- other header code here.... -->
   
    <!-- This line adds the header to the theme -->
    <img id="headerimg" src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="Header image alt text" />
</div>

And there you have it, one header image that you can customise via the WordPress admin panel. An ID is attached to the image for CSS styling where needed.

The example above is quite a simplified version of the header image functionality. It is possible to place text over the image and even have a different image per blog post by using the custom thumbnail functionality, but these are beyond the scope of this blog post. Copy & paste and enjoy!

Errol Sidelsky on February 16 11 / 46 Permalink

Great! Thanks for this – was trying to strip it all out from TwenyTen – what a nightmare.
This was so helpful.

AJ Clarke on March 1 11 / 59 Permalink

Thanks for this tutorial. The only thing I can’t figure out is how to test if an image is defined or not. I don’t want to show a blank img src=”” if there isn’t any header defined.

Matt on March 1 11 / 59 Permalink

Hi AJ,
There’s actually a default image set in the code which it will fall back to if a header image isn’t set. But you could do something like this if you want to be sure:

1
2
3
4
5
6
7
8
9
<?php
$ourhead = header_image();
if(!empty($ourhead)):/* Or ($ourhead != "") */
?>
<!-- This line adds the header to the theme -->
    <img id="headerimg" src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="Header image alt text" />
<?php
endif;
?>

Give that a try.

Linus Bohman on May 23 11 / 142 Permalink

A bit late to the party, but I’ll add my two cents for other potential visitors. I suspect that $ourhead = header_image(); won’t work, since header_image() echoes the image URL. If you change it to $ourhead = get_header_image(); instead it’ll work, since get_header_image() only returns the path – it doesn’t echo it.

Thanks for a good post!

Matt on May 23 11 / 142 Permalink

Hi Linus,
Thanks for the update, looking at the codex you could be right. I never tested the code so hopefully if anyone has an issue your comment will help.

emmanuel on November 30 11 / 333 Permalink

woow, i just tried it on my local host and it works life magic, thanks man

Nicole on January 12 12 / 11 Permalink

This is great! Thank you very much.

lunaz on February 29 12 / 59 Permalink

I found your code & have some of it working, but see an Unexpected T_Endif error unless i comment out the endif; at the bottom. With that commented, it works as normal when there’s a header selected. If I remove the header, it echos the alt text and the actual header text below. I ONLY want the div header to show up if $lheaderimg is not empty. I’m thinking the IF statement isn’t working but can’t seem to figure out why…

functions.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<?php
//Check see if the customisetheme_setup exists
if ( !function_exists('customisetheme_setup') ):
    //Any theme customisations contained in this function
    function customisetheme_setup() {
        //Define default header image
        define( 'HEADER_IMAGE', '' );
        //Define the width and height of our header image
        define( 'HEADER_IMAGE_WIDTH', apply_filters( 'customisetheme_header_image_width', 1000 ) );
        define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'customisetheme_header_image_height', 288 ) );
        //Turn off text inside the header image
        define( 'NO_HEADER_TEXT', true );
        define( 'HEADER_TEXTCOLOR','C0C0C0' );
        //Don't forget this, it adds the functionality to the admin menu
        add_custom_image_header( '', 'customisetheme_admin_header_style' );
        $customHeaders = array (
                'default-img' => array (
                'url' => '',
                'thumbnail_url' => '',
                'description' => __( '', '' )
                )
            );
        //Register the images with Wordpress
        register_default_headers($customHeaders);
    }
endif;
if ( ! function_exists( 'customisetheme_admin_header_style' ) ) :
    //Function fired and inline styles added to the admin panel
    //Customise as required
    function customisetheme_admin_header_style() {
    ?>
        <style type="text/css">
            #wpbody-content #headimg {
                height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
                width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
                border: 1px solid #333;
            }
        </style>
    <?php
    }
endif;
//Execute our custom theme functionality
add_action( 'after_setup_theme', 'customisetheme_setup' );
?>

header.php

1
2
3
4
5
6
7
8
9
10
11
12
13
<div id="lunazheader">
<a href="<?php echo home_url(); ?>">

<?php
$lheaderimg = get_header_image();
if ($lheaderimg);
?>
<div id="header">
<img id="headerimg" src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="Header image alt text" />
</div>

<?php endif; ?>
<?php bloginfo('name'); ?><span class="tagline"><?php bloginfo('description'); ?></span></a></div>

Matt on February 29 12 / 59 Permalink

Hi Lunaz,

Looking at your code you have a slight error here:

1
2
3
4
5
//Yours
if ($lheaderimg);

//Fix
if ($lheaderimg):

Hope that helps!

lunaz on March 1 12 / 60 Permalink

WOOT, thanks much, that did it! Good work on this post & code. :)

Debbie on March 5 12 / 64 Permalink

Great tutorial, thanks very much.

andy on March 30 12 / 89 Permalink

nice tutorial…. was searching for this only.

OffCourse on June 19 12 / 170 Permalink

Hi this tutorial worked fine for me. Is there a way to do the same with custom backgrounds, meaning that we could offer some textures by default for the user to experiment with?

Thank you

Bram on October 19 12 / 292 Permalink

Great explanation, just the code and what it does. Worked like a charm, thanks!

Leave a Comment

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