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

Retrieve the post thumbnail.

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.

Return: (string)

Source file: wp-includes/post-thumbnail-template.php

View source


Parameters

$post_id

(int) (Optional) Post ID. Default is the ID of the <code>$post</code> global.

Default value: null

$size

(string|array) (Optional) Registered image size to use, or flat array of height and width values.

Default value: 'post-thumbnail'

$attr

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

Default value: ''


Explanation

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.


Uses


Source

function get_the_post_thumbnail( $post_id = null, $size = 'post-thumbnail', $attr = '' ) {
	$post_id = ( null === $post_id ) ? get_the_ID() : $post_id;
	$post_thumbnail_id = get_post_thumbnail_id( $post_id );

	/**
	 * Filter the post thumbnail size.
	 *
	 * @since 2.9.0
	 *
	 * @param string $size The post thumbnail size.
	 */
	$size = apply_filters( 'post_thumbnail_size', $size );

	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 string $post_id           The post ID.
		 * @param string $post_thumbnail_id The post thumbnail ID.
		 * @param string $size              The post thumbnail size.
		 */
		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 string $post_id           The post ID.
		 * @param string $post_thumbnail_id The post thumbnail ID.
		 * @param string $size              The post thumbnail size.
		 */
		do_action( 'end_fetch_post_thumbnail_html', $post_id, $post_thumbnail_id, $size );

	} else {
		$html = '';
	}
	/**
	 * Filter the post thumbnail HTML.
	 *
	 * @since 2.9.0
	 *
	 * @param string $html              The post thumbnail HTML.
	 * @param string $post_id           The post ID.
	 * @param string $post_thumbnail_id The post thumbnail ID.
	 * @param string $size              The post thumbnail size.
	 * @param string $attr              Query string of attributes.
	 */
	return apply_filters( 'post_thumbnail_html', $html, $post_id, $post_thumbnail_id, $size, $attr );
}

Changelog


User Contributed Notes

  1. 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>
    
  2. 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().

  3. 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>';
    	}
    }
    
  4. 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>';
    	}
    }
    
  5. 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' ) );
    

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