Giving your users changeable or custom headers in themes

Giving your users changeable or custom headers in themes

Built in to WordPress, and also available for WordPress MU, is the Custom header API. This service allows you to quickly add some code to a theme's functions.php file to make the header area completely customizable. User will be able to upload a header image of their choice on their chosen theme, without affecting other blogs using the same theme.

You may want to try this first on a test site of WPMU.

First, check and see if your theme has a functions.php file included. If it doesn't, make a blank file called functions.php. If it already has code in it, which it will if the theme is widget enabled, then you can paste this code in right before the last ?> tag.

//make changeable header

define('HEADER_TEXTCOLOR', '');
define('HEADER_IMAGE', 'setta.jpg'); // %s is theme dir uri and image filename
define('HEADER_IMAGE_WIDTH', 985);  // make sure these values match the theme header
define('HEADER_IMAGE_HEIGHT', 200);
define( 'NO_HEADER_TEXT', true );

function atypxmas_admin_header_style() {   // change atypxmas to your theme name

// this part adds the header in the admin area
#headimg {
height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
width: <?php echo HEADER_IMAGE_WIDTH; ?>px;

#headimg h1, #headimg #desc {
display: none;}

function header_style() {

background: url(<?php header_image() ?>) no-repeat;}

add_custom_image_header('header_style', 'atypxmas_admin_header_style');  // change atypxmas to your theme name you used above.

And that's it! Everything else is handled internally by WordPress. Please read the code and change the values accordingly for your specific theme, including the filename.

  • IndieLab
    Posted at 10:27h, 07 November Reply


    Another great post:) I will certainly review this code in the coming months as I get back into theming.

  • Barry
    Posted at 11:40h, 10 November Reply

    Ha ha – saved me time and effort yet again. Keep up the good work!

  • IdaWebCo
    Posted at 16:42h, 17 November Reply

    Everything I ever needed to know about changeable headers in themes. Thank you so much!

  • Philip M. Hofer (Frumph)
    Posted at 12:04h, 01 December Reply

    Heya Andrea you missed the if ‘blank’ check so that the words can be hidden when you click hide text, the method you have above won’t allow you to hide text.

    I posted the version with the if ‘blank’ statement here:

    Which will allow you to hide text or show text on both the default and custom header.

  • Websites tagged "themes" on Postsaver
    Posted at 04:02h, 05 January Reply

    […] – Eternal Love saved by punkblackstar2008-12-27 – A8stract NTW saved by xfrancois2008-12-23 – Giving your users changeable or custom headers in themes saved by ckeithley2008-12-23 – Wow, WordPress… saved by SSJ3raditz2008-12-21 – Installation Guide […]

  • ovizii
    Posted at 04:03h, 02 March Reply

    hey andrea, amazing tutorial, I never knew its so easy. I just gave a theme a customizable header in 5 minutes!! incredible!

    Btw. where can I read more about this? I mean where do the uploaded images go?

    @Philip M. Hofer (Frumph):
    the lkink you gave is dead, can someone please check this?

  • David
    Posted at 18:44h, 04 March Reply

    i change atypxmas to? Theme name from CSS?
    what should i do with themes with 2 word names?

  • Amos Elroy
    Posted at 02:17h, 06 March Reply

    That was a good question. First is the name of the theme exactly the name of the them sub-folder containing it, or is it listed somewhere in the theme code? What happens with names containing spaces?

    Another question, if i do not see an Image selection option under the Header Image and Color tab, could it mean the theme I downloaded is not Mu compatible? I believe under regular WP it allows for an image selection as is.

    • eddihughes
      Posted at 18:17h, 24 July Reply

      No, it just needs you need to create a div with id=”header” and style it to the proportion you want.

      in functions.php the #header id is defined dynamically.

      Edit your header.php and add the div, style it to the size you want, margin:0 auto; it and enjoy!

  • David
    Posted at 10:16h, 09 April Reply

    Hey i like to add these function to the classic kubrick theme but it doesnt work. Do you have an idea how i can add custom header to the kubrick theme?

  • Mario
    Posted at 14:49h, 10 May Reply

    Thank you for this. Working on a big WPMU site and this works perfectly!

  • links for 2009-05-09 - Patrick :)
    Posted at 05:14h, 12 May Reply

    […] Giving your users changeable or custom headers in themes – WPMU Tutorials […]

  • deswithat
    Posted at 23:22h, 20 May Reply

    Wpmu always set user file to blog.dir/../../

    How to set custom header image to point that file path ??

  • syamsul
    Posted at 09:36h, 19 July Reply

    Hi I’ve applied your tip to the Primepress theme but it doesn’t seem to be working right. What happens is that it’s added another custom image on top of the existing rotating one. Any ideas?

    Screenshot below

    Thanks in advance

  • Patrick
    Posted at 22:39h, 21 August Reply

    Is it possible to let the user select their own size(height) of the picture?

    and how do i implement it into the code?
    .-= Patrick´s last blog ..21 bloggtips =-.

    • andrea
      Posted at 11:27h, 22 August Reply

      The height is really determined by the theme itself, and the max size is what is listed in the code. You don’t have to use the size in my example, it really depends on the header in your theme.

      • betterfasterstranger
        Posted at 04:33h, 19 October Reply

        Thanks for the tutorial Andrea – having a bit of troub with the dimensions though as I’m using a combination of a percentage for the width and ems for the height which breaks the my function file… any clues?

        • andrea
          Posted at 19:13h, 19 October Reply

          How big is the image? You need the dimensions in pixels of the original header graphic, not the ones on the div.

          • betterfasterstranger
            Posted at 22:05h, 19 October

            OK sweet, I was a bit lazy and just had my header image in the top left of my header div rather than giving it’s own div, so that’s all sorted that out but now I’m getting this error:

            Fatal error: Call to undefined function add_custom_image_header()

            This is my code:

            //make changeable header

            define(‘HEADER_TEXTCOLOR’, ”);
            define(‘HEADER_IMAGE’, ‘/wp-content/themes/nha_blogs/images/people_news.png’); // %s is theme dir uri
            define(‘HEADER_IMAGE_WIDTH’, 448);
            define(‘HEADER_IMAGE_HEIGHT’, 163);
            define( ‘NO_HEADER_TEXT’, true );

            function nha_blogs_admin_header_style() {

            #headimg {
            height: px;
            width: px;

            #headimg h1, #headimg #desc {
            display: none;

            background: url() no-repeat;


            add_custom_image_header(‘header_style’, ‘nha_blogs_admin_header_style’);

            I found the function in wp-includestheme.php :

            function add_custom_image_header($header_callback, $admin_header_callback) {
            if ( ! empty($header_callback) )
            add_action(‘wp_head’, $header_callback);

            if ( ! is_admin() )
            require_once(ABSPATH . ‘wp-admin/custom-header.php’);
            $GLOBALS[‘custom_image_header’] =& new Custom_Image_Header($admin_header_callback);
            add_action(‘admin_menu’, array(&$GLOBALS[‘custom_image_header’], ‘init’));

            Is there something I’m missing to prevent it from playing with the code in functions.php?

            I have written my theme from scratch, it’s pretty basic but has been working perfectly well so far… is there something I should have added to make it talk to theme.php?

            Thanks again from AU !

          • betterfasterstranger
            Posted at 01:18h, 20 October

            a-ha ! fixed it, for I am a tool and put the code into the /wp-admin/functions.php not my theme functions.php… derr!

            Cheers Andrea !

        • andrea
          Posted at 16:32h, 28 April Reply

          Did you try it? The example was a jpg only because the original header was a jpg.

  • Joey
    Posted at 11:34h, 04 September Reply

    I have followed the steps above and I see the Custom Header section in the admin. But, when I upload an image, the next step takes me to the page that lists all the available templates to choose from. The URL show STEP 2 but there is no place to CROP. I have tried multiple files, multiple sizes, etc.

    Nothing happens. The image is never uploaded.

    Am I missing something? Should a file actually be uploaded and if so, where should I be looking?


  • Russ
    Posted at 15:38h, 09 September Reply

    Hi Andrea,

    This is wonderful. Thanks so much for this. I had one question, tho. When I added the code to my functions.php file, I noticed that the original header image disappeared. It wasn’t until I uploaded a new one that the header showed up again.

    Could this be an issue with the theme I’m using? I’m testing using the Inove theme.

    Thanks again,

    • andrea
      Posted at 15:47h, 09 September Reply

      If you didn’t change the line in the code to the path & image in your theme, then that would do it.

  • David cox
    Posted at 10:54h, 25 November Reply

    Hi Andrea,
    I have been trying to insert your sample code in an Artisteer theme, and changing the values as needed, but I keep coming up with syntax errors, I posted on the Artisteer forum and on WPMU forum, where it was suggested I contacted you.

    I do understand the code a bit, but PHP syntax is not my development language, there is a tag out of place, if I paste the sample code in.

    I have all the Artisteer code pasted in this WPMU topic.

    Any example of fitting the code into an Artisteer theme would be most welcomed, and I will link back to any solution from both forums, as I think many other would be interested.

    Kind Regards



  • sid
    Posted at 17:21h, 14 December Reply


    Thanks for the how-to. Going through the steps you provided, I have a quick question, if I change the functions.php file in the theme directory, what exactly ties the header code change to one particular blog? I think this would override the header image for all blogs that use the same theme.

    Where exactly are we setting this for one specific blog, where is that connection made?

    • andrea
      Posted at 17:25h, 14 December Reply

      In the blog’s options table, where the blog header setting gets saved. 🙂

      • sid
        Posted at 17:51h, 14 December Reply

        Thanks for the quick reply,

        So, after I modify the changes in functions.php and drop the header image in my theme folder, I empty the blog’s “Blogname” & “Blogdescription” fields, the header should show up for that perticular blog.

        Any other blog with entries for two options above will have text and not this header?

        • andrea
          Posted at 18:02h, 14 December Reply

          “and drop the header image in my theme folder,”

          The code above adds a menu to the backend of WP. the header gets uploaded there, it doesn’t go in the theme folder.

          Anything done in that menu is only specific for that blog.

  • sid
    Posted at 12:59h, 07 January Reply

    Thanks so much Andrea, It worked after a copied the code from your sample functions.php

  • dandam
    Posted at 18:27h, 26 January Reply

    Many thanks!

    Would be great to link to this from

    With your permission, I’ll share the code there by way of a more detailed entry.

    Again, many many thanks!

  • Thomas
    Posted at 19:17h, 26 January Reply

    Hi Andrea- Did this once on a theme and it worked first try. No tried on another and it works on front end but in admin area i get this:

    Warning: Cannot modify header information – headers already sent by (output started at /home/content/71/4743871/html/wp-content/themes/tstore/functions.php:45) in /home/content/71/4743871/html/wp-includes/functions.php on line 792

    Warning: Cannot modify header information – headers already sent by (output started at /home/content/71/4743871/html/wp-content/themes/tstore/functions.php:45) in /home/content/71/4743871/html/wp-includes/functions.php on line 793

    can you help? thanks!

    • tmo
      Posted at 18:11h, 27 January Reply

      Sorry to bug you.. I had the same image from other custom header theme then uploaded same image again and it threw error with both images…same name. cleared both tried again, smooth sailing! thanks

  • Tony Stark
    Posted at 17:17h, 28 January Reply

    fyi, this is NOT a cookie cutter hack.

    I’ve used this one 5 or themes and just starting to get over the learning curve. I still got 50 or so more themes to do.

    So far, every theme has required significant edits in the style.css and header.php files, as well as editing the example function.php file.

    Why the example in the post is different than the actual one used is beyond me.

    More tips are listed here.

    Thanks for getting me on the right track.

    • andrea
      Posted at 17:28h, 28 January Reply

      It’s not meant to be a cookie cutter hack. 🙂 I think the post states that the *example code* still needs to be edited for your particular theme. It;s meant as a means to understand the process, so you’re not just copy/pasting code in will-nilly with no idea what it’s supposed to do.

      I don’t envy your theme list. Sure they haven’t been done already?

  • Tony Stark
    Posted at 18:56h, 28 January Reply


    Can this be edited so that when a user uploads a png with transparency it will maintain a png and thus its transparency?

    Right now, it automatically converts to jpeg and turns the background black.

    • andrea
      Posted at 19:03h, 28 January Reply

      The custom header API that you’re hooking into with this code is in the core. So that conversion is core, not in the code above.

      • Tony Stark
        Posted at 20:19h, 28 January Reply

        Thanks for the reply.

        I looked into wp-admin/custom-header.php and it looks like it’s happening on the crop. So I tested uploading a png with the correct size and sure enough it maintains its png/transparency.

        I can’t figure out what to edit in custom-header.php though.

        I do see under function step_3 is:

        ‘post_mime_type’ => ‘image/jpeg’,

        which i tried editing to say “$type” or “image/png” or “png”, but nothing changes it still converts to a .jpeg, even when elimanate that string entirely. Somewhere is a function that converts but I can’t read the php code that gives it away.

        At least I can make a tutorial or a notes page to instruct people to crop it to the default size prior to the upload.

  • Paul
    Posted at 00:41h, 10 March Reply

    Thank you! This worked great. I used it in Thesis. The important thing is to insert the URL for the header image into the applicable place in the code. Also rename the theme to your theme name. For thesis, I used thesis_16. Put the image dimensions in, and that’s it. You find the manage header option now in admin under appearance. Awesome code. Thanks!

  • PAtrick Leisegang
    Posted at 19:31h, 18 March Reply

    Is this possible?
    Custom header height decided by user in theme options?

    define(‘HEADER_IMAGE_HEIGHT’, $theme_header_height);

    and then create a input field on the theme options page?

    here is my functions code:

  • Yvonne
    Posted at 16:22h, 28 April Reply

    Hi, quick question. How can I make it to support other image format (i.e. gif, png, etc)?

    Seems like it only produce .jpg and I need it to be a transparent background image.

    Thanks in advance!

  • Mike
    Posted at 13:42h, 16 June Reply

    Isn’t this article only half finished? You’ve not said how to actually place it in your theme?

    I upload an image and nothing happens. I’ve tried adding a #header div and a #headerimg div to my theme where I want the picture but still nothing happens.

    • andrea
      Posted at 15:08h, 16 June Reply

      No, it states to put it in your theme’s functions.php file. If your theme doesn’t have a #header div, use the one your theme has.

  • Cathy
    Posted at 07:38h, 06 August Reply

    I’ve got my custom header working! Now, please, how do I change the admin page comments? It’s hard to narrow down which function to hook into. I’m talking about the text within the _e(‘mytext’) arguments. There seems to be no way to substitute that text with something else. I’ve googled this to death, and I’m no doubt missing something.

Post A Comment