WordPress Custom Headers

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.

Posted in

17 thoughts on “WordPress Custom Headers”

  1. Pingback: wpressd.com

  2. Hi, I was trying to get my header to link to my domain URL, and I guess I broke the code somewhere along the way. I’ve tried everything…but I keep getting the following error: Parse error: syntax error, unexpected ‘<' … on line 53

    Can you help? I'll copy and paste code below. Thank you so much!

    #headimg{
    background: #fff url() no-repeat 0 0;
    color: #333;
    float: left;
    margin: 0;
    padding: 0;
    height: px;
    width: px;
    clear:both;
    }
    #headimg h1,#desc {
    display: none;
    }
    .wrap {
    clear:both;
    }
    #uploadForm {
    margin:0!important;
    }

    #banner{
    background: #fff url() no-repeat 0 0;
    color: #333;
    float: left;
    margin: 0;
    padding: 0;
    height: px;
    width: px;
    }

  3. Hi there !
    i have a question about that :
    if i want to select between a ( background-image or one-color background-color ) !
    like if i don’t want to choose a image but i want a background-color for the header ?
    do you have any idea ?
    P.S : i want to do that from the same conrol panel not from style.css !

    1. …or just upload an image that is just a single color. I know that’s not the most elegant solution, but at least it’s easy.

  4. Thanks for this tutorial – it helped me out.

    I’m still having a problem with the “Display Text” option – it’s not clearing the text when I select “No”. (It is however changing the text color correctly when I select yes and choose a color).

    Have I missed something out? Here’s my functions.php code:

    // gets included in the site header
    function header_style() {
    ?>
    #header {
    background: url() no-repeat;
    height: px;
    width: px;
    }
    #site-title h2, #site-title p {
    color:#;
    }

    #headimg {
    background: url() no-repeat;
    }
    <?php
    }

    add_custom_image_header( 'header_style', 'admin_header_style' );
    // END Custom header image

    Thanks,

    Andy

    1. Oops – it didn’t paste all the code…

      function header_style() {
      ?>
      #header {
      background: url() no-repeat;
      height: px;
      width: px;
      }
      #site-title h2, #site-title p {
      color:#;
      }

      #headimg {
      background: url() no-repeat;
      }
      <?php
      }

      add_custom_image_header( 'header_style', 'admin_header_style' );

      1. It appears that the Twenty Ten theme handles that by adding an if statement in the header_style() function that checks to see if the header text color is blank, and if so, hides the header text:

        if ( ‘blank’ == get_header_textcolor() ){

        }

Leave a Reply to alexmansfield Cancel Reply

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