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.

chat24 Comments

  1. Hansjörg says

    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.

  2. Hansjörg says

    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)

    • Bill Erickson says

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

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

  3. tomph says

    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.

  4. says

    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.

      • says

        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.

  5. says

    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!

  6. Josh says

    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 ) );
    }
    }

  7. says

    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.

Leave a Reply

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