Display the caption of a featured image in WordPress

Have you ever wanted to display the caption of a Featured Image in WordPress? I recently had need to do this and figured out a way to accomplish this.

When you set the Featured Image for a post in WordPress, you can add additional information for the image: Title, Caption, Alt Text and Description.

Set caption for featured image

It makes sense to me that you might want to display the caption for a Featured Image, if entered. My solution to this was to add a function to my functions file to use to display the caption. My function looks like this:

function my_display_featured_image( ) {
    global $post;

    $thumbnail_id = get_post_thumbnail_id($post->ID);
    $thumbnail_details = get_posts(array('p' => $thumbnail_id, 'post_type' => 'attachment'));
    $thumbnail_src = wp_get_attachment_image_src( $thumbnail_id, 'full' );
    $thumbnail_width = $thumbnail_src[1];

    if ($thumbnail_src && isset($thumbnail_src[0])) {
        echo '<div class="featured-image';
        if ( !empty( $thumbnail_details[0]->post_excerpt ) ) echo ' wp-caption';
        echo '" style="max-width: ' . $thumbnail_width . 'px;">';
        if ( !empty( $thumbnail_details[0]->post_excerpt ) ) {
          echo '<p class="featured-image-caption">';
          echo $thumbnail_details[0]->post_excerpt;
          echo '</p>';
      }
      the_post_thumbnail( $post->ID );
      echo '</div>';
    }
}

First, we get the information for the post we’re on. We do this by making the $post global. This will give us access to the id of the post we’re on. From there, we can call get_post_thumbnail_id to get the id of the Featured Image. Once we have the id of the Featured Image, or attachment, that we want, we can then use WordPress’s get_posts to grab the record of the Featured Image. The details of the Featured Image are stored in the variable $thumbnail_details using the call:

$thumbnail_details = get_posts(array('p' => $thumbnail_id, 'post_type' => 'attachment'));

get_posts accepts the arguments of WP_Query so, in our example, ‘p’ is the post id (the id of the Featured Image) which we were able to get using get_post_thumbnail_id. This query returns an object which includes the Featured Image’s caption in the ‘post_excerpt’ value and the description is available in the ‘post_content.’

if ( !empty( $thumbnail_details[0]->post_excerpt ) ) {
  echo '<p class="featured-image-caption">';

I am also grabbing the source of the attachment image and using the width of the image to set some inline CSS (in my particular case I wanted to float the image so I wanted to set the width). wp_get_attachment_image_src gets the url and image dimensions and returns the values in an array.

So, now I have the image’s URL, dimensions and caption. With this information, we can display the image. To check if there is a caption present, I just need to check the value of the post_excerpt returned by my get_posts call.

Finally, I use the_post_thumbnail to display the featured image. In my template file, if the post has a Featured Image, I call my function to display the Featured Image.

if ( has_post_thumbnail() ) : my_display_featured_image(); endif;

That is how I display a Featured Image’s caption.

2 thoughts on “Display the caption of a featured image in WordPress

  1. Thanks for nice piece of code.

    I have one problem with it.

    $thumbnail_src = wp_get_attachment_image_src( $thumbnail_id, 'full' );

    When I change ‘full’ to something else, ‘large’ or my own size ‘category-thumb’ there are no change in post. Image always stay full and uncropped.

    1. doo,

      I think this is an issue with my code where I am calling the thumbnail:

      the_post_thumbnail( $post->ID );

      I am passing the ID of the post, but I believe it should be the size you want. Try changing the size there like:

      the_post_thumbnail( ‘thumbnail’ );

      Does that work properly? Thanks!

Leave a Reply

Your email address will not be published. Required fields are marked *