the_post_thumbnail ( string|array $size = 'post-thumbnail', string|array $attr = '' )

Display 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.

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

View source


Parameters

$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: ''


More Information

Usage

the_post_thumbnail( $size, $attr );

Used by


Source

function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
	echo get_the_post_thumbnail( null, $size, $attr );
}


Changelog


User Contributed Notes

  1. Default Usage

    // Check if the post has a Post Thumbnail assigned to it.
    if ( has_post_thumbnail() ) {
    	the_post_thumbnail();
    } 
    the_content();
    

    Note: To return the Post Thumbnail for use in your PHP code instead of displaying it, use: get_the_post_thumbnail().

  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. This is how you can use these default sizes with the_post_thumbnail():

    the_post_thumbnail();                  // without parameter -> 'post-thumbnail'
     
    the_post_thumbnail( 'thumbnail' );       // Thumbnail (default 150px x 150px max)
    the_post_thumbnail( 'medium' );          // Medium resolution (default 300px x 300px max)
    the_post_thumbnail( 'large' );           // Large resolution (default 640px x 640px max)
    the_post_thumbnail( 'full' );            // Full resolution (original size uploaded)
     
    the_post_thumbnail( 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

    Note: Don’t use these two examples together in the same Theme.

    Example 1. To link Post Thumbnails to the Post Permalink in a specific loop, use the following within your Theme’s template files:

    <?php if ( has_post_thumbnail() ) : ?>
    	<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
    		<?php the_post_thumbnail(); ?>
    	</a>
    <?php endif; ?>

    Example 2. To link all Post Thumbnails on your website to the Post Permalink, put this in the current Theme’s functions.php file:

    /**
     * Link all post thumbnails to the post permalink.
     *
     * @param string $html          Post thumbnail HTML.
     * @param int    $post_id       Post ID.
     * @param int    $post_image_id Post image ID.
     * @return string Filtered post image HTML.
     */
    function wpdocs_post_image_html( $html, $post_id, $post_image_id ) {
    	$html = '<a href="' . get_permalink( $post_id ) . '" alt="' . esc_attr( get_the_title( $post_id ) ) . '">' . $html . '</a>';
    	return $html;
    }
    add_filter( 'post_thumbnail_html', 'wpdocs_post_image_html', 10, 3 );
    
  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(), 'large' );
    	if ( ! empty( $large_image_url[0] ) ) {
    		printf( '<a href="%1$s" alt="%2$s">%3$s</a>',
    			esc_url( $large_image_url[0] ),
    			esc_attr( get_the_title_attribute( 'echo=0' ) ),
    			get_the_post_thumbnail()
    		);
    	}
    }
    
  5. Styling Post Thumbnails

    Post Thumbnails are given a class “wp-post-image” and 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.
    Display the Post Thumbnail with a class “alignleft”:

    the_post_thumbnail( 'thumbnail', array( 'class' => 'alignleft' ) ); 
  6. Post thumbnail sizes:

    //Default WordPress
    the_post_thumbnail( 'thumbnail' );     // Thumbnail (150 x 150 hard cropped)
    the_post_thumbnail( 'medium' );        // Medium resolution (300 x 300 max height 300px)
    the_post_thumbnail( 'medium_large' );  // Medium Large (added in WP 4.4) resolution (768 x 0 infinite height)
    the_post_thumbnail( 'large' );         // Large resolution (1024 x 1024 max height 1024px)
    the_post_thumbnail( 'full' );          // Full resolution (original size uploaded)
    
    //With WooCommerce
    the_post_thumbnail( 'shop_thumbnail' ); // Shop thumbnail (180 x 180 hard cropped)
    the_post_thumbnail( 'shop_catalog' );   // Shop catalog (300 x 300 hard cropped)
    the_post_thumbnail( 'shop_single' );    // Shop single (600 x 600 hard cropped)
    

    Hard cropped sizes have fixed height and width

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