get_the_post_thumbnail( int|WP_Post $post = null, string|array $size = 'post-thumbnail', string|array $attr = '' )

Retrieve the post thumbnail.

Contents

Description Description

When a theme adds ‘post-thumbnail’ support, a special ‘post-thumbnail’ image size is registered, which differs from the ‘thumbnail’ image size managed via the Settings > Media screen.

When using the_post_thumbnail() or related functions, the ‘post-thumbnail’ image size is used by default, though a different size can be specified instead as needed.

Parameters Parameters

$post

(int|WP_Post) (Optional) Post ID or WP_Post object. Default is global $post.

Default value: null

$size

(string|array) (Optional) Image size to use. Accepts any valid image size, or an array of width and height values in pixels (in that order).

Default value: 'post-thumbnail'

$attr

(string|array) (Optional) Query string or array of attributes.

Default value: ''

Top ↑

Return Return

(string) The post thumbnail image tag.

Top ↑

Source Source

File: wp-includes/post-thumbnail-template.php 

function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
	$post = get_post( $post );
	if ( ! $post ) {
		return '';
	}
	$post_thumbnail_id = get_post_thumbnail_id( $post );

	/**
	 * Filters the post thumbnail size.
	 *
	 * @since 2.9.0
	 * @since 4.9.0 Added the `$post_id` parameter.
	 *
	 * @param string|array $size    The post thumbnail size. Image size or array of width and height
	 *                              values (in that order). Default 'post-thumbnail'.
	 * @param int          $post_id The post ID.
	 */
	$size = apply_filters( 'post_thumbnail_size', $size, $post->ID );

	if ( $post_thumbnail_id ) {

		/**
		 * Fires before fetching the post thumbnail HTML.
		 *
		 * Provides "just in time" filtering of all filters in wp_get_attachment_image().
		 *
		 * @since 2.9.0
		 *
		 * @param int          $post_id           The post ID.
		 * @param string       $post_thumbnail_id The post thumbnail ID.
		 * @param string|array $size              The post thumbnail size. Image size or array of width
		 *                                        and height values (in that order). Default 'post-thumbnail'.
		 */
		do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
		if ( in_the_loop() ) {
			update_post_thumbnail_cache();
		}
		$html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );

		/**
		 * Fires after fetching the post thumbnail HTML.
		 *
		 * @since 2.9.0
		 *
		 * @param int          $post_id           The post ID.
		 * @param string       $post_thumbnail_id The post thumbnail ID.
		 * @param string|array $size              The post thumbnail size. Image size or array of width
		 *                                        and height values (in that order). Default 'post-thumbnail'.
		 */
		do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );

	} else {
		$html = '';
	}
	/**
	 * Filters the post thumbnail HTML.
	 *
	 * @since 2.9.0
	 *
	 * @param string       $html              The post thumbnail HTML.
	 * @param int          $post_id           The post ID.
	 * @param string       $post_thumbnail_id The post thumbnail ID.
	 * @param string|array $size              The post thumbnail size. Image size or array of width and height
	 *                                        values (in that order). Default 'post-thumbnail'.
	 * @param string       $attr              Query string of attributes.
	 */
	return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
4.4.0 $post can be a post ID or WP_Post object.
2.9.0 Introduced.

Top ↑

More Information More Information

If the required add_theme_support( 'post-thumbnails' ); in the current theme’s functions.php file is attached to a hook, it must be must be called before the init hook is fired. The init hook may be too late for some features. If attached to a hook, it must be after_setup_theme.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/query.php: in_the_loop()

Determines whether the caller is in the Loop.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/plugin.php: do_action()

Execute functions hooked on a specific action hook.
wp-includes/post-thumbnail-template.php: get_post_thumbnail_id()

Retrieve post thumbnail ID.
wp-includes/post-thumbnail-template.php: update_post_thumbnail_cache()

Update cache for thumbnails in the current loop.
wp-includes/post-thumbnail-template.php: post_thumbnail_size

Filters the post thumbnail size.
wp-includes/post-thumbnail-template.php: begin_fetch_post_thumbnail_html

Fires before fetching the post thumbnail HTML.
wp-includes/post-thumbnail-template.php: end_fetch_post_thumbnail_html

Fires after fetching the post thumbnail HTML.
wp-includes/post-thumbnail-template.php: post_thumbnail_html

Filters the post thumbnail HTML.
wp-includes/media.php: wp_get_attachment_image()

Get an HTML img element representing an image attachment
wp-includes/post.php: get_post()

Retrieves post data given a post ID or post object.
Show 6 more uses Hide more uses

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 12You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Styling Post Thumbnails
    Post Thumbnails are given a class “wp-post-image”. They also get a class depending on the size of the thumbnail being displayed. You can style the output with these CSS selectors:

    	img.wp-post-image
	img.attachment-thumbnail
	img.attachment-medium
	img.attachment-large
	img.attachment-full

    You can also give Post Thumbnails their own class:

    // Give the Post Thumbnail a class "alignleft".
echo get_the_post_thumbnail( $post_id, 'thumbnail', array( 'class' => 'alignleft' ) );
  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Sample Usage

    <?php $pages = get_pages( array( 'child_of' => 1 ) ); ?> 
<ul>
	<?php foreach ( $pages as $page ) : ?>
		<li>
			<?php echo get_the_post_thumbnail( $page->ID, 'thumbnail' ); ?>
			<h1><?php echo apply_filters( 'the_title', $page->post_title, $page->ID ); ?></h1>
			<?php echo apply_filters( 'the_content', $page->post_content ); ?>
		</li>
	<?php endforeach; ?>
</ul>
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Thumbnail Sizes
    The default image sizes of WordPress are “thumbnail”, “medium”, “large” and “full” (the size of the image you uploaded).
    These image sizes can be configured in the WordPress Administration Media panel under Settings > Media.
    Themes may also add “post-thumbnail”. This is how you can use these default sizes with get_the_post_thumbnail():

    // without parameter -> Post Thumbnail (as set by theme using set_post_thumbnail_size())
get_the_post_thumbnail( $post_id );                   

get_the_post_thumbnail( $post_id, 'thumbnail' );      // Thumbnail (Note: different to Post Thumbnail)
get_the_post_thumbnail( $post_id, 'medium' );         // Medium resolution
get_the_post_thumbnail( $post_id, 'large' );          // Large resolution
get_the_post_thumbnail( $post_id, 'full' );           // Original resolution

get_the_post_thumbnail( $post_id, array( 100, 100) ); // Other resolutions

    Register new image sizes for Post Thumbnails with: add_image_size().
    To set the default size for Post Thumbnails see: set_post_thumbnail_size().

  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Post Thumbnail Linking to the Post Permalink

    This example shows the 5 latest Post Thumbnails linked to their Post permalink.

    $posts = get_posts( array( 'posts_per_page' => 5 ) );
foreach ( $posts as $_post ) {
	if ( has_post_thumbnail( $_post->ID ) ) {
		echo '<a href="' . get_permalink( $_post->ID ) . '" title="' . esc_attr( $_post->post_title ) . '">';
		echo get_the_post_thumbnail( $_post->ID, 'thumbnail' );
		echo '</a>';
	}
}
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by Shaikh Muhammad Arif Uddin —

    Remove width and height attributes from the returning html

    get_the_post_thumbnail function produces html with img tag which includes width, height, src, class, alt and title attributes. The following code snippet is useful if someone wish to remove width and height attribute.

    This function provides 'post_thumbnail_html' filter before returning the html.

    add_filter( 'post_thumbnail_html', 'remove_thumbnail_width_height', 10, 5 );

function remove_thumbnail_width_height( $html, $post_id, $post_thumbnail_id, $size, $attr ) {
    $html = preg_replace( '/(width|height)=\"\d*\"\s/', "", $html );
    return $html;
}
  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Post Thumbnail Linking to large Image Size
    This example links to the “large” Post Thumbnail image size and must be used within The Loop.

    if ( has_post_thumbnail() ) {
	$large_image_url = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), 'large' );
	if ( ! empty( $large_image_url[0] ) ) {
		echo '<a href="' . esc_url( $large_image_url[0] ) . '" title="' . the_title_attribute( array( 'echo' => 0 ) ) . '">';
		echo get_the_post_thumbnail( $post->ID, 'thumbnail' ); 
		echo '</a>';
	}
}
  8. Skip to note 8 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by jesperstender —

    You can set more than just classes –
    If you want to optimize your SrcSet values you can do something like this

     echo get_the_post_thumbnail($post->ID, 'WhateverSize-Large', array('title' => 'WhateverTitle', 'sizes' => '(max-width: 320px) 288px, (max-width: 375px) 343px, (max-width: 425px) 393px, (max-width: 540px) 493px, (max-width: 768px) 320px, (max-width: 999px) 435px, 288px'));

    etc.

    Normally in a grid, the srcset can go 100vw – which is sometimes way too big –
    this method lets you control that.

  9. Skip to note 9 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by joshcanhelp —

    Post thumbnails in a listing context are often linked to the content they’re representing. Instead of adding that every time, here is a filter you can add that will do it automatically based on an `$attr` passed in.

    /**
 * Link thumbnails to their posts based on attr
 *
 * @param $html
 * @param int $pid
 * @param int $post_thumbnail_id
 * @param int $size
 * @param array $attr
 *
 * @return string
 */

function wpdev_filter_post_thumbnail_html( $html, $pid, $post_thumbnail_id, $size, $attr ) {

	 if ( ! empty( $attr[ 'link_thumbnail' ] ) ) {

		$html = sprintf(
			'<a href="%s" title="%s" rel="nofollow">%s</a>',
			get_permalink( $pid ),
			esc_attr( get_the_title( $pid ) ),
			$html
		);
	 }

	return $html;
}

add_filter( 'post_thumbnail_html', 'wpdev_filter_post_thumbnail_html', 10, 5 );

    Expand full source codeCollapse full source code

    Just “add the above to your functions.php file” (there’s probably a better place for it) and use it like this in a template file:

     'my-custom-class', // classes
		'link_thumbnail' => TRUE, // yes please link my thumbnail
	]
);
?>

You must log in before being able to contribute a note or feedback.