Blog

Sharing WordPress tips and tricks as I find them

WordPress Post Thumbnails with Captions

This tip is for all themes that support WordPress’ Post Thumbnails (also known as Featured Images). If you’re using Thesis, this does not apply to you since Thesis uses its own Post Image solution.

In version 2.9 WordPress added  support for Post Thumbnails, which allowed you to upload an image using the standard uploader, and select it as the image that represents the post. This image could then be used throughout the site in thumbnails of different sizes, and displayed on the post itself.

Mark Jaquith provides an excellent summary of WordPress Post Thumbnails, so I’m not going to repeat it.

I’m building a client’s site with Genesis and using this feature. One issue that came up was Captions. The WordPress uploader let’s you specify a caption for an image, but when you use the_post_thumbnail() it just displays the image.

I couldn’t find any documentation on retrieving the image’s caption, so I asked Mark. I thought it would be useful to share it.

WordPress stores images as their own post, and it stores the caption as the post’s excerpt. To display the image and it’s caption, use this:

The first line creates a div called “featured image” so that we can style it later with CSS. The second line displays the post image. The third line uses get_post() to get the “featured image” post and pull out the excerpt, which is where the caption is stored. We then wrap it in a span with a class of “caption” for styling. Finally we close the original div.

To get the description instead of caption, use post_content instead of post_excerpt.

24 Comments

  1. Thanks, just what I was looking for!

  2. Thanks, Bill. I’ve been trying to figure out how to add the caption to the thumbnail for a while now.

  3. Hi

    just a simple nweebee Question:

    Where do I have to put that code?

  4. Thanks, but it seems, that I need a little bit more help ;-)

    I use twentyten. Do I have to create a seperate file custom_functions.php ?
    or do I have to put the code in the function.php?

    • Bill Erickson says:

      Sorry, I assumed you were using Thesis.

      TwentyTen uses the post thumbnail in the header of the page, so you’ll need to go into header.php and add it there. If you wanted to use post thumbnails at the top of the post (like in this example) you’d need to:
      - Remove the code in the header that sticks a post thumbnail there
      - Create a new image size for the content area (the one in the header is too big)
      - Stick the code above in single.php above the_content().

      Refer to Mark Jaquith’s post ( http://markjaquith.wordpress.com/2009/12/23/new-in-wordpress-2-9-post-thumbnail-images/ ) for how to work with post thumbnails.

  5. Again thanks for the answer. What I would like to do, is to use thumbnails together with excerpt on the front-page. So far I managed this by using a plugin. My specific problem with this is, that there are no ceptions (which I also would like to appear)

  6. Hi,
    How do we put css styling to the caption for a thumbnail?
    The text seems to be un-styled..

    • Bill Erickson says:

      You could wrap a span around it and apply CSS to that:

      echo ‘‘.get_post(get_post_thumbnail_id())->post_excerpt.’‘;

  7. Thanks a ton! I couldn’t find this anywhere on the WordPress Codex.

  8. Is there any way to display captions for multiple featured images? I have a template set up with 3 different images using the ‘MultiPostThumbnail’ plugin.

    • Bill Erickson says:

      I don’t know how that plugin works, but assuming the featured images are attachments, like they are with normal featured images, and you have access to their post IDs, the above code will work with your template as well.

  9. This post is pretty close to what I need but doesn’t quite get me across the finish line.

    I need to show the image description. For example, in the media library I have a photo with a caption and a description—the description reads “Homer at the beach”. All our images have the description field filled out.

    How can we retrieve that rather than the caption?

    • Bill Erickson says:

      The caption is stored as the excerpt, and the description is stored as the post content. So to get the description, use this instead: echo get_post(get_post_thumbnail_id())->post_content;

      If you ever want to check out what values are assigned to the post, just grab the post object and do a print_r($post). This is what I did to figure the above out:

      $thumb = get_post(get_post_thumbnail_id());
      print_r($thumb);

      That shows me all the information associated with the post.

      • Thanks. After re-reading the original and thread it clicked when you pointed out that images are stored like posts. It just never made sense to me that so many blogs kept saying to use post_content.

        Thanks for the reply, a little fog was lifted today.

  10. Thank you for this. I was looking for this information everywhere. For some reason, it doesn’t seem to be in the codex.

  11. Thank you! I have been trying to figure this out and this was the simplest and quickest solution I found. Kudos!

  12. Thanks for posting! Using a custom theme, added has_post_thumbnail(), dropped the function in the functions file, called it from my template and it works like a charm!

  13. Great post! Exactly what I was looking for. Thanks for sharing!

  14. Brilliant, thanks! It took me ages to find this, but saved a lot of heartache.

    I’d just like to point out, if you’re using Frontend Uploader for WordPress, and need to set the description of an uploaded file, you can use this page :
    http://wordpress.org/support/topic/plugin-frontend-uploader-layout-and-collecting-data?replies=13
    and modify it to look like this:
    add_action( ‘fu_after_upload’, ‘my_fu_after_upload’ );

    function my_fu_after_upload( $attachment_ids ) {
    // do something with freshly uploaded files
    // This happens on POST request, so $_POST will also be available for you
    foreach( $attachment_ids as $att_id ) {
    // Format the title
    $author = $_POST['name'];
    $author .= ‘ ‘ . $_POST['email'];
    // Change the description
    $caption = ‘Upload by ‘ . $_POST['name'];
    $caption .= ‘, ‘ . $_POST['email'];
    $caption .= ‘ ‘ . $_POST['post_title'];
    // Sanitize input from user
    $author = sanitize_text_field( $author );
    wp_update_post( array( ‘ID’ => $att_id, ‘post_title’ => $author, ‘post_content’ => $caption ) );
    }
    }

  15. Inserting a caption worked, but not styling it with CSS. Then I realized the caption showed without entering the function, but it doesn’t have a CSS class and I cannot find a way to style it.

  16. Thanks for this little and shiny snippet! That made my day. :-)

Join the Conversation

If you'd like to include code in your post, please post it to http://gist.github.com and include a link.