25. June 2012
von Blackbam

Update: There was a short intverview regarding this Plugin by expertentesten.de: https://www.expertentesten.de/news/interview-david-stoeckl-custom-header-images-plugin/(language is german).

Why does WordPress need another Header Images Plugin? Really, there are a lot of Plugins for this purpose so why did I have to write another one? The answer is: All these plugins have a lot of code, it is hard to extend these by oneself and unfortunatly none if these is really simple to maintain, extend and to understand. I was searching for hours for the right header image Plugin which provides the functionality that i needed in a simple clean and easy way, without custom tables and buggy built-in uploads, wihout required theme support and so on. So here is my answer: A quick and easy WordPress Plugin to do this job.


  • Simple and easy management of header images
  • Each possible state is covered, by using the WordPress template hierarchyfor diffentiation
  • The Media Library is used for image management, images are saved by URL copy/paste (so external images can be used, too)
  • Requires no extra tables
  • NEW: Support for Custom Post Types (Single Custom Post Images) and Custom Taxonomies (Taxonomy Page Images)
  • Clean install/uninstall
Be free to post improvement ideas and feature request as a comment to this post.


>> Download this Plugin <<

  1. Upload the Plugin to your wp-content/plugins/ folder
  2. Activate the Plugin
  3. Go to Settings -> Header Images and insert the image URLs (get the URLs from the media library)
  4. Paste one of the following codes into your theme:

NOTE:This code must be put into PHP brackets!

// standard code
if(function_exists('chi_display_header')) { chi_display_header(); }

or this code, use concrete numbers for width and height in pixels:

// f.e. chi_display_header(960,250); for header images with 960 px width and 250 px height
if(function_exists('chi_display_header')) { chi_display_header($width,$height); }

Warning: You can only use conditional query tags after the posts_selection action hook in WordPress (the wp action hook is the first one through which you can use these conditionals). For themes, this means the conditional tag will never work properly if you are using it in the body of functions.php, i.e. outside of a function (http://codex.wordpress.org/Conditional_Tags).


============ UPDATE: 2014-02-01 ==========

Some functions were added for better flexibility:

chi_get_header_image_url(); // get only the URL of the header image


chi_get_header_image_link(); // get only the Link of the header image


chi_get_display_header_data($width=-1,$height=-1); // get the full output of the plugin into a variable, but do not display it


Responsiveness tutorial (short)

For the sake of responsive web design, you will not be happy to put out the same header image on every device (as huge header images are not good for mobile devices to load). Therefore I suggest the following solution which should work well for you:


  1. Instead of calling  chi_display_header(); you call chi_get_header_image_url(); and pass it to a Javascript variablet
  2. Install the timthumb library on your WordPress installation
  3. Use Javascript to get the image in the desired size from timthumb.php by passing the original image url


How to change header images...

  • Go to Settings ->Header images (general images)
  • Meta Boxes at the bottom of post / page edit screen
  • Category add/edit screen


Q: The Plugin is not displaying the header images correctly. What is wrong?

  • The function code must be pasted into one of your template files, the best place in most cases of use is the bottom of header.php
  • This Plugin uses conditional tags. Please make sure that your wp_query object has been loaded correctly, before the code is executed.

Dieser Eintrag wurde am 25. June 2012 um 1:01 in der Kategorie Plugins, WordPress veröffentlicht. You can book the comments for this article RSS 2.0. Feedback, discussion, commendation and critics are welcome: Write a comment or trackback.


Warning: Use of undefined constant Ext_related_links - assumed 'Ext_related_links' (this will throw an Error in a future version of PHP) in /home/.sites/609/site1266/web/blackbams-blog/wp-content/themes/SilentWoodsByBlackbam/single.php on line 75

Already 93 comments belonging to "Custom Header Images Plugin for WordPress":

Kommentare abonnieren (RSS) or URL Trackback

Blackbam     says:

on 02. May 2013 at 19:58 on clock


you should make sure that the following:

1. Links must be enabled, the link must be correctly specified (if it is working for most of the images, but not for a specific one this might be a bug, please report it)
2. If you use custom output, make sure that you use the [link] shorttag properly in your output - if not, please try again with using custom output and tell me, if this solved the problem - the linking functionality is basically the same as the images functionality, so if the images work, the links should work, too.

Hope this helps.

janet saw     says:

on 21. May 2013 at 06:24 on clock

Brilliant - after weeks of searhing I found this site and plugin. Thank you so much!!!! I've also made a donation and urge others who have fund this useful to do the same, it's more than worth it.

Blackbam     says:

on 21. May 2013 at 13:04 on clock

Thanks a lot I recieved your donation. It is a great motivation to hear about people who value the work on free WordPress Plugins to keep up good work :-)

Lukas Gruber   says:

on 11. June 2013 at 10:36 on clock


first of all, thank you for a great plugin, that makes look and feel of wordpress websites very customizable.

However I have one issue using this plugin I cannot solve: i managed to set up different header banners for all sites except for site I configured as a home page. On the home page header banner doesnt show at all.

I set up links for all header banner and included code () into template "header.php". I also tried to included this code into "index.php" template but it didnt work in order to make header image visible on a home page.

I´m using twenty twelve template.

Thank you in advance for any ideas to solve this issue.

Blackbam     says:

on 11. June 2013 at 19:42 on clock

Hello Lukas

1. Did you try to set the Image URL in the "Custom Header Images" Box on the Page settings?

2. Did you try to set the Image URL under Settings -> Header Images ->"Home Image URL" as well as "Front page URL" ?

3. Did you check if your "Home Page" is set correctly under Settings -> Reading ?

4. Write the following code into your template

 if(is_home()) { echo "should see me on home"; }

If you do not see anything on your "home" page (if you do not confuse it with your "front page"), then check if the corresponding part of your template is loaded. If you see this text, but you do not see the image - check if the image URL is correct and report this bug to me again.

5. If you STILL cannot find the problem, try to embed the image for THIS one page manually in your HTML-code - however, it SHOULD work.

Please tell me if this helps!

Lukas Gruber   says:

on 12. June 2013 at 13:52 on clock

Hello, thanx a lot for help. Advice #2 worked for me - i didnt set header image urls under settings. Lukas

londonpeanuts     says:

on 09. July 2013 at 23:50 on clock

Hi- I'm trying to make my header image responsive and have probably spent dozens of fruitless hours trying to do so. I know absolutely nothing about code so am at a total loss. Is a new update coming soon to make header images responsive easily? Or what can I do that is easy to understand for someone who knows nothing about code?

Blackbam     says:

on 17. July 2013 at 23:14 on clock

Hello it will not be possible to make your header images responsive without some litte peace of code.

But I visited your site now and I think you have managed to do it finally. Congratulations!

Richard   says:

on 24. July 2013 at 12:37 on clock


I installed your plugin and it works fine! I could set a custom header image, but I wasn't able to make it clickable.

I want to link the start page and the header, because I want to give the option to return to the start page by clicking the header.

I activated the link header feature, I set a global header and a data link "http://localhost/wordpress/" (its still on my pc so dont worry about localhost).

Do you have any ideas how to solve this issue?

Blackbam     says:

on 25. July 2013 at 16:29 on clock


it seems like your settings have been made correctly. Please do the following:

1. Set the header image for some concrete page - check if the link works then

2. The header image links usually work with javascript - make sure that you do not have ANY Javascript-Errors on your page

3. Check the source code - please check if the correct link is set in the data-href-Attribute of the header image

4. You could use custom output - maybe you want to put the link, using [link], in the HTML "a" tag, so it will work without Javascript.

One of these steps should help you.

anne     says:

on 09. August 2013 at 05:01 on clock

Hello mister Blackbam,
first i really thank you for this plugin very usefull, clean and simple for utilisation
But! is it possible to put the image in % for the width with an overflow:hidden for the height?
insted to put an image in 1920px :-).

Blackbam     says:

on 11. August 2013 at 15:21 on clock

Hello anne, this is definitly possible. Just use the function "Custom output" (and the link "restore default") at the bottom of the settings page and adjust everything to your needs.

anne     says:

on 19. August 2013 at 11:45 on clock

thanks a lot

Linda   says:

on 23. September 2013 at 08:03 on clock

I really like this plugin. If it could support image maps, it would be even better. Can you let me know if there is some way in image maps may be used in combination with this plugin?

anne     says:

on 23. September 2013 at 21:51 on clock

Hello Blackbam, is there a way to get image header in post who are in subcategories http://cie-emilievalantin.fr/spectacles/au-repertoire(category)/les-fourberies-de-scapin(category)/ :-)

Blackbam     says:

on 24. September 2013 at 20:36 on clock

@Linda: Hello I must admit I did not think of this possibility yet. I will turn this into a feature request and impelement it in the next version of the plugin, but this will take some time.

You can achieve your goal with a hackarround: Add a unique ID and the html usemap-tag to the image, after the page is loaded. This way is a bit cumbersome. But currently there is no other way yet.

@anne: Of course it is. Just check out the settings of the Plugin in detail.

Boris     says:

on 06. November 2013 at 18:56 on clock


I'm trying your plugin but encounter an issue.
I precise i'm not using default template but the Phoenix template from Goodlayers.

When i put your code in the header of my template, just after body tag line, my header background image is visible in top of the page and the site is under.

If i put the code in the header container tag code, my header background image is not visible and with Ctrl+U, there no HTML code corresponding.

I also verify that the code is not in a conditional query.

Can you help me please ?

much.fun   says:

on 02. January 2014 at 11:57 on clock

Hallo, kann ich auch für posts und pages relative Pfade zu den Bildern angeben ? Falls ja,wo gebe ich sie an, und in welchem Format? Danke :-)

Blackbam     says:

on 08. January 2014 at 20:49 on clock

@Boris: Sorry for the late answer. Please check different locations for the code. I am sorry that I cannot check how to make this thing working for each and any theme.

@much.fun: Es sollte funktionieren wenn du einfach vor dem Link die URL weglässt (also anstatt http://example.com/images/bla.png sollte /images/bla.png) auch funktionieren, also immer der gesamte relative Pfad direkt nach dem Domain Namen. Aber bitte vorher testen.

BALYAN     says:

on 09. January 2014 at 16:46 on clock


Morten   says:

on 28. January 2014 at 11:13 on clock

Hi. is it possible to use your plugin for two versions of header image at different screen widths (responsive):

- one custom header image at 480px screen width
- second custom header image for higher @ media screen widths

BTW, this plugin is awesome, thank you very much for your hard work.

Blackbam     says:

on 28. January 2014 at 20:09 on clock

Hello Morten I think achieving this aim requires some custom work, as it is not built into the Plugin currently.

So I can think of two possible solutions which require you to do some programming work:
1. If you have a small number of pages affected, you just should write a little jQuery script which exchanges the images on small resolutions
2. If you have a large number of pages, you could extend the Plugin by writing an additional field for "mobile images". This requires some work to do. If I have the time (and currently I have not) I will implement this functionality in a Plugin update in the future.

Morten   says:

on 29. January 2014 at 11:17 on clock

Thank You very much for the answer :) Regards Morten

much.fun   says:

on 08. February 2014 at 23:21 on clock

Hallo, Danke zunächst für Deine Antwort zu meiner letzten Frage. :-) Nun habe ich das Problem, dass das Plugin in einem child theme von Yoko von Elmastudio super läuft, aber in einem child theme von twentytwelve weigert sich das Plugin hartnäckig. Bevor ich lange weiter nach einer Lösung suche, würde ich gern wissen, ob das Plugin überhaupt mit twentytwelve zusammenarbeitet. Danke & viele Grüße.

andrewjohnchapman   says:

on 16. February 2014 at 17:26 on clock

Hi, can I put the code into my child theme, and if so into what file should it go. So far I just have style.css and content.php. Thanks, Andrew

much.fun   says:

on 19. February 2014 at 16:14 on clock

Hallo, ich stelle gerade fest: Wenn man alles richtig maht, geht es gleich viel besser .. Damit hat sich meine Frage erledigt ... Danke für das tolle Plugin!

Movie2k     says:

on 20. February 2014 at 09:06 on clock

This is what exactly what i've looking for. I hate those plugin that bloated in features that i don't need. this one is right for my needs

Blackbam     says:

on 24. February 2014 at 14:56 on clock

@andrewjohnchapman: Basically, yes - of course you can put the code into your child theme. You just have to put it to the place where you like the "Header Images" to appear (this may be anywhere except of the loop). In most times you put the code into header.php of your theme - so if you do NOT overwrite header.php in your child theme, you may want to put the code in the main theme - or you may want to overwrite header.php in your child theme for update reasons.

dipti sharma     says:

on 01. April 2014 at 20:24 on clock


I want to add facebook , twitter icons in header of my blog. I used image widget to do this but images are not coming together. Also there is no option to header option to add image .

How do i do this.

Also , I dont have plugin option in my Dashboard.

Please , let me know on this. Regards, Dipti Sharma

Blackbam     says:

on 02. April 2014 at 19:21 on clock

Hello there are no plugin options in the Dashboard right now. You have to configure the Plugin on the Plugins' settings page.

If you are going to add social icons to the header, you should be able to figure out the CSS for this yourself.

muchfun   says:

on 11. May 2014 at 21:07 on clock

Hallo, ich weiß noch eine Frage: Ich habe eine Seite erstellt und ihr ein header image zugewiesen. Was mache ich, um einer Anhangseite das gleiche header image zu zu weisen?
Wenn ich auf der erstellten Seite (zB http://fluegge.net/wunderland/italien) ein Bild anklicke, dass sich dann auf der Anhangseite öffnet (zB http://fluegge.net/wunderland/italien/italien-8/ ), so fehlt auf der Anhangseite ein header image :-( Ich habe mir jetzt erstmal mit einem Standardbild beholfen (Globale Bild Default URL), aber das ist irgendwie uncool.

Ich würde mich über eine Anregung freuen :-) und vielen Dank nochmals für das plugin

snap   says:

on 02. October 2014 at 17:01 on clock

about the responsive design code, do you have any real life sample we could have a look at?

Blackbam     says:

on 03. October 2014 at 16:56 on clock

Hello there with basic programming knowledge it should be easy to create some real life sample. There are different possibilities how to achieve the responsiveness.

tom   says:

on 27. December 2014 at 22:14 on clock

Are you still maintaining this plugin??
I put the code into header.php and specified a default link/url for the desired default image.
Then I put a different link to a different image for the 'home' page -- on the home page's page settings per se...but the default image still appears on the 'home' page, which is not called 'home" though...
It is also not clear how to work with this plugin when all the images are the same width but different heights....what line in the plugin code should be changed so the plugin ignores the height value?? -- better yet, does not even require width, height declared??
Or where to change the code so it writes <img src= etc. etc. instead of using background url css??
Thank you, Tom

tom   says:

on 27. December 2014 at 22:49 on clock

I did figure out a few things...and I know I had it working...but now it sets the div and no image appears in the div...image sizes are set...puzzling!!

Joseph Lema     says:

on 07. January 2015 at 23:52 on clock

how can we get each custom header images to link to different urls?

Joseph Lema     says:

on 09. January 2015 at 00:35 on clock

Clickable link function is not working on Custom Header Images

wam     says:

on 03. March 2015 at 21:56 on clock

I need to be able to place at least 2 images (with links) on the right side of the header. Can I do that with your plugin? Thanks.

Blackbam     says:

on 11. April 2015 at 21:42 on clock

Hello Tom, yes the Plugin is maintained but not too often (there should be an update within the next few weeks). The original purpose of the Plugin was not to use images of different heights, I will think of integrating an solution vfor this. If you are a coder the Plugin code should not be too complicated for you to adapt. For the Problem with the "home" page, please consult the WordPress Template hierarchy.

Blackbam     says:

on 11. April 2015 at 21:43 on clock

Well it should work if you enable the feature. The Plugin will have a new debug session within the next few weeks.

Blackbam     says:

on 11. April 2015 at 21:48 on clock

Haha well no. With some dirty hack you maybe could duplicate the Plugin, rename it and rename all functions. Then you can use it twice ;-)

abu   says:

on 14. August 2015 at 07:16 on clock

is there any option for adding titles and sub titles on the header image?

Blackbam     says:

on 16. September 2015 at 16:08 on clock

Hello abu unfortunatly not yet. If I have the time I may add this feature.

Leave a comment: