Beginner's Guide for WordPress - Start your WordPress Blog in minutes.
Choosing the Best
WordPress Hosting
How to Easily
Install WordPress
WordPress Plugins
View all Guides

How to Enable Custom Header Images Panel in WordPress 3.0

Last updated on by
Special WordPress Hosting offer for WPBeginner Readers
How to Enable Custom Header Images Panel in WordPress 3.0

If you guys haven’t had a chance to test out WordPress 3.0, then you are missing out. We have created numerous posts about WordPress 3.0 features and have shown WordPress 3.0 screenshots as well. One of the note-worthy upgrade in this version is a new default theme called Twenty Ten. This theme has a lot of great features enabled, but one of the features that a lot of users want is the Custom Headers Panel. In this article, we will share with you how you can enable custom headers with a back-end admin panel in WordPress 3.0.

What exactly will this feature do?

It will create a tab in your admin panel which will allow you to change header images. You can register default images if you are a theme designer to give users more options. It also allows users to upload custom images for the header. Last but certainly not the least, this feature utilizes post thumbnails on single post pages. If your post thumbnail is big enough to fit the header size, then it will use your post thumbnail as the header instead of the default image. If your thumbnail is bigger, then it will crop it down for you.

Custom Header in WordPress 3.0

Watch the Screencast

How to Add this?

We took the code straight from Twenty Ten’s functions.php file. You need to paste the following codes in your theme’s functions.php file.

/** Tell WordPress to run yourtheme_setup() when the 'after_setup_theme' hook is run. */
add_action( 'after_setup_theme', 'yourtheme_setup' );
if ( ! function_exists('yourtheme_setup') ):
* @uses add_custom_image_header() To add support for a custom header.
* @uses register_default_headers() To register the default custom header images provided with the theme.
* @since 3.0.0
function yourtheme_setup() {
// This theme uses post thumbnails
add_theme_support( 'post-thumbnails' );
// Your changeable header business starts here
define( 'HEADER_TEXTCOLOR', '' );
// No CSS, just IMG call. The %s is a placeholder for the theme template directory URI.
define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' );
// The height and width of your custom header. You can hook into the theme's own filters to change these values.
// Add a filter to yourtheme_header_image_width and yourtheme_header_image_height to change these values.
define( 'HEADER_IMAGE_WIDTH', apply_filters( 'yourtheme_header_image_width', 940 ) );
define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'yourtheme_header_image_height',	198 ) );
// We'll be using post thumbnails for custom header images on posts and pages.
// We want them to be 940 pixels wide by 198 pixels tall (larger images will be auto-cropped to fit).
set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true );
// Don't support text inside the header image.
define( 'NO_HEADER_TEXT', true );
// Add a way for the custom header to be styled in the admin panel that controls
// custom headers. See yourtheme_admin_header_style(), below.
add_custom_image_header( '', 'yourtheme_admin_header_style' );
// … and thus ends the changeable header business.
// Default custom headers packaged with the theme. %s is a placeholder for the theme template directory URI.
register_default_headers( array (
'berries' => array (
'url' => '%s/images/headers/berries.jpg',
'thumbnail_url' => '%s/images/headers/berries-thumbnail.jpg',
'description' => __( 'Berries', 'yourtheme' )
'cherryblossom' => array (
'url' => '%s/images/headers/cherryblossoms.jpg',
'thumbnail_url' => '%s/images/headers/cherryblossoms-thumbnail.jpg',
'description' => __( 'Cherry Blossoms', 'yourtheme' )
'concave' => array (
'url' => '%s/images/headers/concave.jpg',
'thumbnail_url' => '%s/images/headers/concave-thumbnail.jpg',
'description' => __( 'Concave', 'yourtheme' )
'fern' => array (
'url' => '%s/images/headers/fern.jpg',
'thumbnail_url' => '%s/images/headers/fern-thumbnail.jpg',
'description' => __( 'Fern', 'yourtheme' )
'forestfloor' => array (
'url' => '%s/images/headers/forestfloor.jpg',
'thumbnail_url' => '%s/images/headers/forestfloor-thumbnail.jpg',
'description' => __( 'Forest Floor', 'yourtheme' )
'inkwell' => array (
'url' => '%s/images/headers/inkwell.jpg',
'thumbnail_url' => '%s/images/headers/inkwell-thumbnail.jpg',
'description' => __( 'Inkwell', 'yourtheme' )
'path' => array (
'url' => '%s/images/headers/path.jpg',
'thumbnail_url' => '%s/images/headers/path-thumbnail.jpg',
'description' => __( 'Path', 'yourtheme' )
'sunset' => array (
'url' => '%s/images/headers/sunset.jpg',
'thumbnail_url' => '%s/images/headers/sunset-thumbnail.jpg',
'description' => __( 'Sunset', 'yourtheme' )
) );
if ( ! function_exists( 'yourtheme_admin_header_style' ) ) :
* Styles the header image displayed on the Appearance > Header admin panel.
* Referenced via add_custom_image_header() in yourtheme_setup().
* @since 3.0.0
function yourtheme_admin_header_style() {
<style type="text/css">
#headimg {
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
#headimg h1, #headimg #desc {
display: none;

That is jibbrish to me. Please Explain

Ofcourse, this might look jibrish to some of you. This is mostly for theme designers, but we will do our best to break it down. Before we start make sure you copy and paste this code in your code editor, so you can make the changes necessary.

Note: We are using /images/headers/ as the directory where you will store your default header images.

  • You start the code out by creating a function yourtheme_setup().
  • In line 21, we define the default header image. Note there is a variable %s which is basically a placeholder for the theme directory URI.
  • Line 25 and 26 is where you define the image width and height. By default it is set to 940px wide and 198px high. You can change it by editing those two lines.
  • Starting from line 42, we start registering the default headers. These are the images that will show up as a radio button option in your admin panel. If you need more options then simply follow the format being used.
  • In line 95, we choose the header styling. You do not need to change these settings because you alreadyd efined them in Line 25 and 26.

That is all what you are doing for the theme’s functions.php file. Next we are going to go into how you are going to add this to your theme.

Code to add in your Theme

This code will most likely go in the theme’s header.php file. You can style it however you like.

// Check if this is a post or page, if it has a thumbnail, and if it's a big one
if ( is_singular() &&
has_post_thumbnail( $post->ID ) &&
( /* $src, $width, $height */ $image = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), 'post-thumbnail') ) &&
$image[1] >= HEADER_IMAGE_WIDTH ) :
// We have a new header image!
echo get_the_post_thumbnail( $post->ID, 'post-thumbnail' );
else : ?>
<img src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="" />
<?php endif; ?>

What is this code doing?

  • First, it is checking if it is a single post or a page. It also checks if this post/page has a thumbnail, and whether it is big enough.
  • If the page is a single page and has a big enough thumbnail, then it displays the post thumbnail specific for that post.
  • If it is not a single page, or the post thumbnail is not big enough, then it will show the default header.

We hope this tutorial was helpful. We got a few emails asking about this tutorial, so we broke the code down from the Twenty Ten theme. If you have any questions, then feel free to ask in the comments.

Editorial Staff at WPBeginner is a team of WordPress experts led by Syed Balkhi. Page maintained by Syed Balkhi.

WPBeginner's Video Icon
Our HD-Quality tutorial videos for WordPress Beginners will teach you how to use WordPress to create and manage your own website in about an hour. Get started now »


  1. snehal says:

    Hello Thanks for great information. I followed all your steps correctly and its successfully done. but one problem is header image blank space is showing on home page also. Plz Help me…

  2. Martin says:

    How can i change the name from “header” to “footer” in the appearance menu ?

  3. Christine says:

    I know I am bringing up an OLD post but – THANK YOU!! Worked perfectly :)

  4. Rajesh Khatri says:

    I just read and apply to my local site, i have certain questions:

    1) when i add images into featured image it will directly save in “wp-content/upload” Folder can i set this to in my theme folder like “mytheme/image/header” ? how can i do this plz suggest me.

    2) and second point is when i add image it is also create thumbnail (150 x 150 & 300x 95) size images , can i stop this auto create images?

    3) doesn’t understand below code, what does that mean:

    array (
    ‘berries’ => array (
    ‘url’ => ‘%s/images/headers/berries.jpg’,
    ‘thumbnail_url’ => ‘%s/images/headers/berries-thumbnail.jpg’,
    ‘description’ => __( ‘Berries’, ‘yourtheme’ )

    It will be great pleasure if some one guide me.

    Hoping for early response, Thanks in advance,


  5. forrestmiller says:

    Hello, Thanks for this informative post. I followed you steps and it worked out perfectly except for one thing. My header is aligned to the left and i cant seem to figure out how to center it. How can I make this happen?

  6. tronicman says:


    thanx for the tutorial, but as I am more a designer than programmer, I could need a little bit of extra information ;-)

    (I understand HTML and CSS, know a little bit of working with WordPress, but don´t know much about PHP)

    ´cause that doesn´t work at all.

    When changing:

    ‘cherryblossom’ => array ( ‘url’ => ‘%s/images/headers/cherryblossoms.jpg’, ‘thumbnail_url’ => ‘%s/images/headers/cherryblossoms-thumbnail.jpg’, ‘description’ => __( ‘Cherry Blossoms’, ‘yourtheme’ ) ),

    what exactly do I have to write into the URL, instead of the “%s”?

    A total path like “” ??

    Or does it “know” its path (means, that it is in the theme called “mytheme” in the “themes” folder within the “wp-content” folder, and I only have to write “mytheme//images/headers/cherryblossoms.jpg”?? Or shouldn´t I change the “%s” at all?

    Do I have to change something in the CSS? And if yes, where and what?

    Could you please give me some hints?

    • wpbeginner says:

      @tronicman %s is the path to your theme. So %s points to and then you specify afterwards like /images/headers/

  7. Berry says:

    Hello, I did everything as in the tutorial and it all works, featured images are shown in the header of the posts but everytime I post something I get this error:

    Warning: Cannot modify header information – headers already sent by (output started at C:xampphtdocswordpresswp-contentthemesTiendeveenfunctions.php:239) in C:xampphtdocswordpresswp-adminasync-upload.php on line 2691

    Everything works, you only get this error when posting with a featured image which is irritating, any help please?

  8. Robert says:

    Thanks for the post. In my theme I have 4 different custom post types. I would like to use the header image functionality but also be able to set a different default header image for each of 4 custom post types. Is anyone aware of a plugin/resource for accomplishing this?

    • Editorial Staff says:

      You can’t do it with the current header panel because that sets an image for all pages. However you can do it by hard coding the custom-post-type specific page template.

  9. pegasus says:

    hey there, hope you can lend me a hand, i’ve cut and pasted the code on my functions.php file and header.php, and everythings works fine as long as i’m logged into the worpress’ dashboard, the problem is when i log out and try to log back in, it shows nothing but a blank page, i’ve styled the old default theme that came with the 2.9 release (was it 2.8??).
    any thoughts?

    • Editorial Staff says:

      Most likely, you are leaving additional spaces in the functions.php file that is causing this error.

  10. chartinael says:

    the intro vid on says, that a custom header is doable for different pages. However, I don’t seem to figure out, how to assign a specific header for cats, pages, or posts. Any thoughts?

    • Editorial Staff says:

      Yes, if you look at the default Twenty Ten codes it does that. Basically how it is working is that it takes your featured image that you attach for that post or page, and then displays it there. In Twenty Ten there are other criterias set such as if the width of the featured image is “this big” then show the featured image as the header image, if not then show the default header image.

      • chartinael says:

        Hey there, it doesn’t work for me:

        have image sized as header images, have in folder x on my server
        click on featured image link in post/page
        enter url
        click insert into post (no other option), i’d expect something like safe as header for this post, page, section god knows what.

        then image gets uploaded whereever cursor was at time of clicking and that’s it. Header image still the default image as set in appearance / header section. Am I doing something wrong? Theme is virgin. I thought I’d try things out first.

  11. Nacho says:

    Is there a way to apply this to categories?

    • Editorial Staff says:

      Do you mean custom header images on categories??? Because by default this image is shown on all pages.

  12. Carkod says:

    Thank you so much, especially for taking the time to do the screencast, it helps a lot!

  13. Piet says:

    Great tips, but in your example of functions.php the %s (as template directory) still links to twentyten instead to the child theme!

    I am trying to replace the default header image (path.jpg) in admin with my own, but cannot accomplish that as long as %s links back to the twentyten parent theme…

    Any chance on a solution?

  14. cathy says:

    I have created a theme based on ET-Starter. I have made some adjustments and everything is going swimmingly. The one thing I cannot figure out is how to adjust the strings within the _e(‘string’) sections on the page. For example, the string I am trying to replace reads ‘If you don’t want to upload your own image, you can use one of these cool headers.’

    The only thing I can find on replacing these strings have been with respect to translating to another language. It’s very murky in the code (for me) to ascertain the hook for this filter.

  15. Matti says:

    Could this be modified to show all the different headers on one page? I am thinking about whether this could be developed into a slideshow of header images, with the ability to add new images through the wordpress custom header admin.

    • Editorial Staff says:

      It could be if you know jQuery… but we haven’t seen a plugin like that yet.

      • Matti says:

        Is there a simple way of editing this to show all images at the same time? A small edit to the php that anyone could help me with?

  16. Micah says:

    Is there a way to take the existing header photos displayed by the header_image() tag and randomly call them on each page load? It would be great to upload 10-20 at a time and then let the theme randomly pull one of the photos to display.

    • Editorial Staff says:

      Not by default… but you can use the old image rotation trick that we mentioned in our site. Use the search feature :)

      • Micah says:

        Right, I saw that article but realized the structure in the 2010 theme is updated. I wasn’t sure if others had already done this with the header_image() function. It would be pretty cool if somehow you could enter a variable into the parens, like this: header_image(‘random’). Is there a way to write something into functions.php for this? Otherwise, I guess I’ll have a try with your method, thanks.

  17. LimeCake says:

    Hi i recently downloaded a theme but it hasn’t got the custom header option like my current theme has. Do i just copy and paste the code in this page? i’m an IT idiot so i have no idea about CSS or anything like that. will copying this code create a menu in my wordpress template that will enable to change my header easily or do i have to manually go into the stylesheet and change the header image? thanks!

    • Editorial Staff says:

      If you have no idea about CSS and such, then we recommend you hire a developer. Because you still have to modify the theme files to make the styling right for that theme.

  18. Pete says:

    Thanks so much… great minds think alike ;)

Add a Comment

We're glad you have chosen to leave a comment. Please keep in mind that all comments are moderated according to our comment policy, and all links are nofollow. Do NOT use keywords in the name field. Let's have a personal and meaningful conversation.