How to use WordPress’s gallery feature

WordPress 2.5 included a photo gallery feature and an image uploader that uses Flash. The documentation for these features is spotty to non-existent. I have been hunting around for information on this feature and experimenting with it on my gardening site. This is what I’ve found out so far.

A new template for your theme

The first thing you need to realize is that with the introduction of this feature a new template was added to the WordPress core: image.php. If your theme is lacking this template, the gallery feature will still work, but not to its best advantage. Blog Almighty has the best instructions I’ve found for creating this template if it isn’t included in your theme.

Update your stylesheet

Furthermore, the gallery makes use of some styling that needs to be included in your styles.css file. You can find the additional classes and suggested attributes in the WordPress support forum.

These two things will ensure that your gallery has the right look and functionality after it is published. But how do you get your photos uploaded and create a gallery when you’re writing a post?

What to expect when it’s published

First of all, we’ll talk about how it works as a gallery when published to your blog. In the post you’ve created, there will be a display of thumbnails with captions under them.

This is one row from a series of thumbnails. The caption text is larger here than on a single medium image.

This is one row from a series of thumbnails. The caption text is larger here than on a single medium image.

When a reader clicks on a thumbnail image, she is taken to a medium size image on its own page, with more text if you have chosen to add it.
The key elements to a gallery image. The presence of duplicate popularity ratings is probably due to a faulty image.php design on my part.

The key elements to a gallery image. The presence of duplicate popularity ratings is probably due to a faulty image.php design on my part. (Click on image to enlarge.)

Above the image will be a title, which will function as a link back to the main post. The reader will be able to comment on this picture without going back to the main post. (Comment form not shown in illustration.) He will also be able to move through the rest of the gallery by clicking on Next and Previous links, which may themselves be thumbnail images, without going back to the main post. If the reader clicks on the medium image, she will be taken to the largest size image, with no text at all, and will have to use the Back button to get back. (Screenshots taken from this post.)

How to get these results when editing your post

Now, how to make this work on the back end? When writing a post, place your cursor in your post where you want the gallery to be. At the top right of the writing textbox on Write Post page, you will see the words Add Media and a little icon for Add an Image (circled in red). Click that, and a new box/screen pops up, asking you for the files to upload. You can select one or several files (if your browser, such as Firefox, is compatible) at once. Then click Upload files.

This is what your screen looks like if you upload one photo.

This is what your screen looks like if you upload one photo.

After the files are uploaded, you have an opportunity to modify the information associated with each one. (Refer to screen shot above.) Title is what will go above the photo when it’s on a page all by itself, and will also become the title tag in the html. Caption will be the small text under the photo, but will also function as the alt tag in the html. (This is regrettable, as the alt tag is to explain the image when it can’t be seen, and often should be worded differently than a photo caption would be. It can be edited by hand when in code view, but will add extra time to your posting.)

Finally, you can type in a Description. This will show up when the medium image is on its own page, but otherwise won’t be seen. I leave the Link URL alone, and then choose an Alignment based on whether it is a full width image, in which case I use center, or less than full width, when I choose left or right depending on how I want the text to wrap. Then click Hide in the upper right, and click Show in order to modify the next photo in the series you uploaded. When you’re done, click Save All Changes. After the changes are done, you will see a button that says Insert Gallery into post. Click that button and you’re done. These last instructions are not illustrated above, but this brief movie demonstrates these steps rather quickly.

No thumbnails, just single images in the post

If you want to use it to show single images, you upload the images in the same fashion. Only the Caption will be visible on the post page, because when the medium image is clicked it shows the image file itself. The Title and Description will never be visible. Choose the alignment as you did when preparing images for a gallery. Finally, instead of clicking Insert Gallery into Post, click Insert into Post, and the image will be inserted where the cursor is.

A mix of single images and a gallery requires a dummy

If you want a mix of single images and a gallery, you have a problem. Every image that is uploaded while editing a post will become associated with that post and will show up in its gallery. To keep the single images out of the gallery, you must keep them from being attached to that post. Open another tab in your browser and start another dummy post. Upload the image that you want to display as a large single image in your real post, and save it. Then delete the dummy post. Go back to your real post and place the cursor where you want the single image to be. Click the Add media button, but choose Media Gallery instead of Upload. You will find the image you uploaded from the dummy post there. Write a caption if you wish, choose your alignment option, and insert it into your post. It will not show up in the gallery for that post. (I have Margaret Roach to thank for this tip.)

Did this help? Or, do you know a better way?

As I said in the beginning, I’ve learned this much through trial and error and extensive use of search engines. If anyone has tips or corrections, please offer them in the comments. If my explanation hasn’t been clear enough on any point, I’ll give it another shot if you bring it to my attention.

Comments on this entry are closed.

  • damon marshall

    Most helpful, thank you so much!

  • Very helpful, great explanation of how this works

  • I am working on my blog and I am adding Galleries but I cant get the thumbnails to be lager than a rectangle. Any ideas?

  • Check Settings – Media. You can specify the height and width for thumbnails there. If those settings are correct it is possible your theme is constraining the size of them somehow.

  • VERY helpful… some sense of it all at last! :))

  • Is there a way to add images to the gallery from direct urls, instead of uploading them to wordpress media library?


  • Satyadeep, I have never tried, so I don’t know. I prefer to upload my own images and store them on my own webhosting. Have you tried asking your question at the official WordPress support forum?

  • Thanks for your research, Kathy! :-)
    As of this writing I’m using Wordpress 3.1. At least there (but I’m sure it’s there in older versions, too) you can exclude images (that you uploaded while editing an article) from a gallery by simply going to the HTML view and editing the [gallery ...] command. It has an “exclude” option and if you want to exclude specific images it looks like this:
    [gallery link="file" exclude="182,184,190,191,192"]
    Now, those numbers are Wordpress’s internal IDs and to get such an ID you have to look at the HTML code of an image you added to the article but don’t want to have in the gallery. Look for the tag:

    The number at the end of the class name (here: 182) is the ID of that image.

    That solves one problem.

    However, I still don’t know how to make a single image appear like an image that’s inside a gallery? I excluded the single images because I don’t want them to show up in the gallery but I *do* want them to show up in the same way like gallery images show up (ie: in a centered layer on top of the article with the rest of the page dimmed).
    The way it is now is awful: if a visitor clicks on one of the gallery-excluded images he/she just gets the image as the only thing in the browser (direct URL to the image). :-(
    Any solution to that?

  • Stefan, thank you for stopping by and offering your thoughtful comments. First, let me point out that you are commenting on an old post. I certainly agree that a lot has changed in WordPress. In fact, I developed a series of tutorials on image handling in WordPress combined with a demo website to illustrate the ideas in the tutorials. It sounds to me like you are using a gallery plugin in addition to the standard WordPress image handling. But I wonder if it would work the way you want it to if you changed it to link url instead of file url before inserting it in the post.

  • thanks a lot. It’s so easy when you know how to do it and where to click. Thanks for sharing!

  • Thanks for these tips! I ran into the problem of having regular images & a gallery in one post. I used the dummy post trick and it worked! I hope WordPress finds an easy way to deal with this issue.

  • Jenny

    Hellow, what I’m trying to do is to make somethink like you described in here but with a little change.

    What I want to do is, to put single image and gallery-view on one site, so when you’re clicking on the thumbnail the single image is loaded on the left – for example. Do you know how to realize something like that or a plugin which could do that for me? I really need this. (Customer and their wantings ‘n stuff…)

    Greetings from Germany!
    // Jenny

  • Thanks so much for the tip on creating a dummy to get an image in the text but not the gallery. That had been driving me nuts!