As of December 2011 every plugin hosted on WordPress.org has the option to display a visually pleasing banner image at the top of its plugin page.

If you are publishing a quick ad-hoc plugin you might not want to go to the effort, but for everyone else, especially plugins that represent a brand we consider a good banner to be a must. Not creating a banner leaves your plugin looking distinctly unprofessional. Besides, it need not be elaborate; a simple colored gradient is better than nothing at all.

Banner Dimensions and Font

The basic plugin banner is 772x250 pixels wide-by-tall and it will be overlaid with the plugin's name in 30px Helvetica Neue font. The rounded black box containing the plugin name will be aligned 30px from the banner's left margin and 24px from it's bottom margin. You can see this in the following annotated white banner image:

Annotated WordPress Plugin Banner with Dimensions and Font Size and Family
Annotated WordPress Plugin Banner with Dimensions and Font Size and Family

Design with Plugin Name in Mind

Be aware that WordPress.org will overlay your plugin name on top of your banner. This mean you should not add your plugin's name to your banner images but you should design the banner to accommodate the name being overlaid.

Note the dimensions and font in the annotated banner image above. You get a left margin of 30px and a bottom margin of 24px and then the length of your plugin name at 30px using Helvetica Neue determines how much space you need to reserve for your plugin name.

Use Chrome's "Inspect Element" to Preview

Given that the plugin name overlays your image it can be a real pain to get your banner design "just right" so we came up with a way to use Chrome's "Inspect Element" to see what it will look like. Using Chrome navigate to any plugin page that has a banner on WordPress.org and right-click on the banner; you'll get a menu option to select the element inspector:

Screenshot showing Chrome's "Inspect Element" Developer Tool
Screenshot showing Chrome's "Inspect Element" Developer Tool

Then upload your banner to a live site somewhere on the web via FTP or other method (note our screenshot below shows using a local file:/// reference, which does not work.)

Next add a CSS select for the #plugin-title element and add a CSS background-image property to reference a local copy of your banner:

#plugin-title {
  background-image: url(http://example.com/path/to/where/banner/can/be/found/your-banner-772x250.png);
}
Swapping Out the Banner for your Own on a WordPress.org Plugin Page
Swapping Out the Banner for your Own on a WordPress.org Plugin Page

The last step is to right-click on the exiting plugin name to have Chrome select its HTML element in the HTML viewer and then you can double click on the inner text of the <h2> element change the plugin's name so you can preview your own plugin's name:

Previewing your Plugin's Banner and Name as it will Appear
Previewing your Plugin's Banner and Name as it will Appear

There is supposedly a method that allows you to add ?banner_url=<url-to-your-banner> to the end of your own plugin's URL but I was never able to get it to work. Besides, the browser approach is more flexible so why not just use it?

Optionally Add High DPI/Retina Images

In July 2012 WordPress.org also added optional support for high DPI (a.k.a. "Retina") images at a dimension of 1544x500 pixels. If you provide a high DPI image WordPress.org will serve it instead when it senses that the device viewing is a high DPI device such as an Apple MacBook Pro with Retina Display.

Banner Image for in Normal DPI a.k.a. Non-Retina Format
Banner image for WordPress Related Posts plugin in normal DPI a.k.a. non-Retina 722x250px format
Plugin Banner in High-DPI a.k.a. Retina Format
Banner image for WordPress Related Posts plugin in high-DPI a.k.a. Retina 1544x500px format

If you are going to provide a High DPI image it's probably best to design at the larger size and then also save the image to the smaller size. However, since we are a plugin coding blog and not a design techniques blog we might not be giving you the best advice here; consult your favorite web designer for best practices instead.

Save in Either .PNG or .JPG Format

Choose one of these two (2) image formats for your banner. Again we are not a design techniques blog but I think the rule of thumb is to use .JPG for photos and for everything else use .PNG. But again, consult your favorite web designer:

PNG vs. JPEG by Louis Brandy
PNG vs. JPEG: The First and Last Webcomic by Louis Brandy

Keep the Design Simple

There is a well-known aphorism that goes something like this:

"Perfection is finally attained not when there is no longer anything to add but when there is no longer anything to take away."

We believe the same is true for plugin banner design; the more you add the worse your results will be. Most visitors will only spend a split-second of their attention to decide it they want to learn more about a plugin so we sure not to overwhelm them with complexity in your graphic.

So plugin banners should only attempt to capture the most important aspect of the plugin in an easy-to-comprehend visual and not be used as a menu of features. If the banner can capture the visitor's attention then they are more likely to actually read about the features and benefits in the description below.

We think the Tumbler Importer is a good example of this done right (except they could have done a better job of reserving "white space" around the plugin name):

Banner Image for the Tumbler Importer WordPress Plugin
Banner Image for the Tumbler Importer WordPress Plugin

Three Example Banners

No such post would be complete without three examples so we selected several plugins we developed for clients to showcase. Note that in all cases our clients had their own designers design the banners, we just built the plugins for them:

Banner Image for Pardot's Plugin Page on WordPress.org
Banner Image for Pardot's Plugin Page on WordPress.org
Banner Image for Content.ad's Plugin Page on WordPress.org
Banner Image for Content.ad's Plugin Page on WordPress.org
Banner Image for Revostock's Media Gallery Plugin Page on WordPress.org
Banner Image for Revostock's Media Gallery Plugin Page on WordPress.org

Update

So Scott Reilly (@coffee2code) tweeted that he was "surprised we didn't include the few basic nuts&bolts, i.e. banners go in assets/ and image filename syntax." Fair point.

The reason we didn't include those things because we plan to write other posts where we drill down into the technical aspects of actually publishing plugins via Subversion (SVN) so we didn't do it here. And honestly it was late, I'd spent all day writing the post, still had other work to do and so I just wanted to click "Publish" and be done with it. :)

Still, after thinking about it this post does feel incomplete without that information so I decided to go ahead and update it since I don't know how long it will be before we can write the follow up post. Also Otto came along and mentioned as few things I thought it would be good to add in the body of the post.

Banner File Naming

Banner image files need to be saved with specific names, respectively:

  • banner-772x250.png or banner-772x250.jpg, and
  • banner-1544x500.png or banner-1544x500.jpg

Where to Store Banner Files

If you don't already know how to publish a plugin using Subversion then you can wait your our tutorial or better yet look for another tutorial on the web to explain using SVN to publish your plugin, like this one by @jalaine.

If you do know how you use Subversion for your plugin but don't yet know how to get the banner to work then here's how. In the root directory for your plugin you'll have these three directories:

  • branches
  • tags
  • trunk

Add a 4th directory called assets and that's where you commit your banner files from up to the plugin repository's SVN server. This is also where screenshots go now, btw.

Important note: It's really easy to get confused and think you need to create an assets directory in the root of your plugin, especially if you are using GitHub to maintain your plugin's development history. By nature you won't have an assets directory above your plugin directory in a Git repository unless you proactively structure it that way which wouldn't make sense for people who might want to use your plugin directly from GitHub.

So, be sure to put your assets directory as a top level directory for SVN:

  • assets
  • branches
  • tags
  • trunk

Keep Banner File Sizes Small

As Otto mentioned, keep your images small. WordPress.org offers free plugin hosting so don't look a gift horse in the mouth, and you want your own plugin page to load fast anyway. And if you are using .PNG files be sure to shrink them with something like PunyPNG (thanks @photomatt.)

And Beware the Multiplication Sign

As Scott Reilly commented below, be careful not to cut-and-paste banner file names from WordPress blogs that contain the multiplication sign (×) instead of what you really want which is is the lowercase 'X' (x). Anytime WordPress sees two numbers separated by an x — i.e. 772x250 — it does you the "favor" of converting to a multiplication sign — i.e. 772×250 — and that doesn't work for a banner image file name.

But thanks to Scott we've made sure our post has banner file names that are safe to copy-and-paste.

Summary

So in summary:

  • Design a Banner Image
    • Design as 1544x500 pixels for High DPI/Retina
    • Also save as 772x250 pixels
  • Accommodate the Plugin Name
    • Uses 30px Helvetica Neue
    • With a 30px left margin and 24px bottom margin
    • Use Google's Chrome to Preview
  • Save in One of:
    • .JPG for Photos
    • .PNG for Anything Else
  • Keep the Design Simple
    • Focus Visuals on One Key Aspect
  • About Banner Files
    • Name the Files Correctly
    • Store the Files in the Right Place
    • Keep the Files Small
    • And use a real lowercase x

Related Links and Posts

We just went in-depth about the banner but didn't cover how to get your banner actually published. We didn't cover that because we plan a future post to cover all the technical aspects of published plugins. But until we do you might have questions we didn't answer so we thought it would be nice to give you some other links that might answer them for you:

  1. Last December, we added header images to the top of plugin screens. Since then, we’ve made more changes to the plugin directory and started supporting HiDPI images for those plugin headers as well. by Otto (@Otto42) on Make WordPress Plugins (2012)

  2. Add Banner to your WordPress.org Plugin Page by Neil Sweeney (@WolfieZero) (2012)

  3. Plugin authors can now add custom header images to their WordPress.org listings by Ryan Imel (@ryanimel) on WPCandy (2011)

  4. How to Add a Custom Banner Image to your WordPress.org Plugin Page on velvet blues (@velvetblues) (2011)

  5. How to Add a Header Image to your WordPress.org Plugins on gravitationalfx.com (@gravitationalfx) (2011)

  6. Been giving a lot of thought to how to give plugin authors more control over their plugin pages. In WordPress custom headers have been hugely beneficial in people’s ability to make a theme their own without having to be a designer. (And designers can make them really sing.) by Matt Mullenweg (@photomatt) on Make WordPress Plugins (2011)

Did We Miss Anything?

Got any suggestions? Things we should have mentioned? Let us know in the comments.

19 thoughts on “Adding a Banner Image to your WordPress Plugin Page

    • Hi @Carrie,

      Thanks for your comment. I really like what you’ve done with the banner, especially the image; I think that works really well.

      However I do have a few suggestions about the wording which gave me the idea to do a “Banner Content Makeover”. If you wouldn’t mind I’d like to do a quick post showing how we would change it, but I don’t want to put you on the spot and showcase your work if you’d rather we not.

      -Mike

      Reply
      • Hey Mike,
        I’d be glad for your feedback! The plugin was created by David Wang (@blogjunkie), so I’d feel better if we had his permission. I’d certainly be interested in your comments.

        Cheers,
        Carrie
        p.s. I’ll shoot David a message so he can chime in.

        Reply
        • Hi @Carrie,

          Good deal. I’m thinking 3 specific things to tighten up the wording and make it easier for people to recognize it’s value at a glance. Looking forward to “meeting” David.

          Reply
  1. Great article, but yes, one thing is missing: How do we get this into our SVN repo? And how would we do that from within our local git repo (as we develop on GitHub mainly – the official repo isn’t for development, according to Otto/official sources).

    Reply
    • Hi @Kaiser,

      Thanks for visiting and for your comments. Yes, I didn’t cover SVN or Git because I was planning to cover those details in a future post. Since I’ve returned to blogging less than a month ago I’m realizing just how hard it is to decided on the scope of a post and also how to handle the inevitable comments from people who rightly mention that I didn’t cover something when they don’t know I’m planning to cover it in the near future.

      Anyway, I added some related links to this post and might even post a quick update that at least mentions the file structure.

      Reply
      • Hey @Mike,

        didn’t know that and just responded to “Things we should have mentioned?”. We just published a plugin to the repo but couldn’t get SVN integrated to Git seamlessly and therefore have no banner at the moment. Thought it might be a good opportunity to ask for further Clarityfication.

        Reply
        • @Kaiser,

          LOL, good point! As for Git we’ve been using Mercurial for our private repositories so I’m going to have to do research to be able to write about GitHub. On the other hand I’m started to put a lot of code up on GitHub at our NewClarity GitHub account so I’m becoming much better acquainted with Git. On the other hand, I still like Mercurial much better.

          Reply
          • Note: For new plugins created now, the plugin system will auto-create the assets directory for you. Older plugins won’t have this directory, but when I put the new screenshots handling code in, I changed it to create this directory on new plugins by default.

          • @Otto Any hint or guidance from you on how to integrate the assets with an (already in use) Git repo? Currently we only got it inside an `~/assets` subdir, but no idea how to “map” that to the official repo / seamlessily integrate that via git-svn.

          • @Kaiser – We’re developing a command line tool to do that work for us. It’s a lot more complicated than it sounds though, hence why we are still developing it vs. having already finished it. :)

  2. I would also suggest trying to keep the file size as small as possible. While we do use a cdn for serving those images, every bit helps.

    Also, the banner URL trick only works for the logged in owner of the plugin.

    Reply
    • Hi @Otto,

      Great points, thanks. I’m working on an update to this post so I’ll be sure to add to the main content.

      BTW, I tried to get the banner trick to work on plugins of mine when I was logged in and still couldn’t get it to work. Are you sure there’s not a bug? Does the plugin need to already have a banner for it to work?

      Reply
      • The plugin does not need to have an existing banner, but you do need to be a “contributor” of the plugin in order to use it. That is, your username must be in the list of contributors in the readme.txt file. Case matters.

        Reply
  3. Nice write-up. One additional tip that warrants mentioning is that the banner filenames should have an ‘x’ (lowecase ‘X’) between the height and width dimensions, not a ‘×’ (multiplication sign).

    This becomes especially worthy of mention in tutorials (and *for* the tutorials themselves) because WP will typically convert an ‘x’ joining two numbers into the multiplication sign (e.g. 300×200). Some people copy-and-paste what they find in tutorials like the above when naming their images, which will leave them wondering why the banner doesn’t appear after they’ve otherwise followed all the directions. It can be difficult to spot.

    When specifying the filename, you may want to use &#120; instead of × (e.g. 300x200).

    Reply
    • Hi @Scott,

      Thanks for stopping by and for the comment. That’s a really great point about the multiplication sign and one I did not know. I’ll update the post to make sure all my references are real ‘x’ characters and also add a section to the update.

      Thanks again.

      Reply

Leave a reply

required

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code lang=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre lang="" extra="">