This post is about adding the custom header functionality to a WordPress theme. If you were looking for existing themes that support custom headers, I suggest you try the WordPress free themes directory.

Since version 2.1, WordPress has allowed custom headers to be added to themes. I don’t really have a use for it on my own blog, but I’d like to offer that functionality in the themes I release to the public. So last night I waded though some documentation and existing code to figure out just how it’s done. It’s actually pretty simple, so even if you don’t have much experience with WordPress theming, you should be able to follow along.

1. Define the header properties

First you need to tell WordPress a few things about your header. There are four things you should specify:

1. Header image location (the path to the image)
2. Header width
3. Header height
4. Text color

These definitions go in the function.php file in your WordPress theme. Here’s what it looks like:

define('HEADER_IMAGE', '%s/images/header.jpg');
define('HEADER_IMAGE_WIDTH', 960);
define('HEADER_IMAGE_HEIGHT', 150);
define('HEADER_TEXTCOLOR', '444444');

As you can see, I use a file called header.jpg and I keep it in a folder called images within my WordPress theme. You’re free to name your image something else if you prefer, or even put it in a different folder. You’ll want to leave the “%s/” as it is though, since it points to the location of your theme directory. The next two lines specify the width and height of the header image. WordPress will allow the user to crop any picture they upload to the dimensions you specify to make sure their images fit perfectly into your design. The last line is for setting the color of the header text. The user will have the option of changing colors or hiding text all together, so just set the color to whatever works best with your default background and rest assured that if they change the background, they can change the text to match.

2. Add some style

Now you need to create a function that will provide the styles associated with header image in your theme. All you’re really doing is wrapping some CSS in a PHP function like this:

function header_style() {
?>
<style type="text/css">
#header{
background: url(<?php header_image(); ?>)  no-repeat;
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
}
#header h1 a{color:#<?php header_textcolor();?>;}
</style>
<?php
}

That’s the very minimum for styling the header. All it does is set the header styles you defined earlier. Notice the closing PHP tag before the styles start and the opening PHP tag after the style ends.

3. Admin styles

You’ve styled the header for the web site itself, but there’s a little bit more to do still. You see, WordPress allows the user to preview their changes in the admin panel, so you have to set some styles for that as well. You can use (almost) the same code as before, but make sure to add any code that you have in your regular style sheet that applies to the header so that they admin preview and the actual site display the same way. For example, the code for the theme I’m working on at the moment looks like this:

function admin_header_style() {
?>
<style type="text/css">
#headimg{
background:#ffffff url(<?php header_image() ?>) bottom center no-repeat;
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
text-align:center;
text-transform:uppercase;
}
#headimg h1{font-size:2.5em; padding:25px 0 0 0; margin:0 0 15px 0;}
#headimg h1 a{border-bottom:1px solid #dddddd; color:#444444; text-decoration:none;}
#headimg p{color:#777777; font-size:1.2em;}
</style>
<?php
}

The most important thing to note is the function name. Make sure it’s different than the name of the first function. Other than that, just use the styles from the first function along with any header related styles you have in your stylesheet.

4. Add it to the theme

Finally, you need to alert the theme about all the work you just did, so it can use all that code you wrote:

if ( function_exists('add_custom_image_header') ) {
add_custom_image_header('header_style', 'admin_header_style');
} 

5. Test it out!

Now you can save your functions.php file and go to your WordPress admin panel. Go to Appearance>Custom Header and test your new creation!

If you have any questions or comments about the process, leave a note below.