the_post_thumbnail()WP 2.9.0

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.

1 time — 0.001739 sec (very slow) | 50000 times — 6.79 sec (fast) | PHP 7.1.2, WP 4.7.3

No Hooks.

Return

null. Nothing (null).

Usage

the_post_thumbnail( $size, $attr );
$size(string|int[])
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order).
Default: 'post-thumbnail'
$attr(string|array)
Query string or array of attributes.
Default: ''

Examples

2

#1 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)

// Other resolutions
the_post_thumbnail( [ 100, 100 ] );  
0

#2 Thumbnail as a link to the post

Use the following code to show thumbnail image inside a link to a post. This code need to be used inside the WordPress Loop:

<?php if ( has_post_thumbnail() ) { ?>
   <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>" >
	   <?php the_post_thumbnail(); ?>
   </a>
 <?php } ?>
Using hook

Use the post_thumbnail_html hook. In this case the image will be a link to the post immediately when the_post_thumbnail() function is called. The code must be added to the functions.php theme file:

add_filter( 'post_thumbnail_html', 'my_post_image_html', 10, 3 );

function my_post_image_html( $html, $post_id, $post_image_id ) {

	$html = '<a href="' . get_permalink( $post_id ) . '" title="' . esc_attr( get_post_field( 'post_title', $post_id ) ) . '">' . $html . '</a>';

	return $html;

}
0

#3 Thumbnail-link to the original size

An example showing how to create a thumbnail that refers to the original picture size:

<?php
if ( has_post_thumbnail() ) {

	$large_image_url = wp_get_attachment_image_src( get_post_thumbnail_id(), 'large');
	?>

	<a href="<?= $large_image_url[0] ?>" title="<?= the_title_attribute('echo=0') ?>" >
		<?php the_post_thumbnail( 'thumbnail' ) ?>
	</a>

	<?php
}
?>
0

#4 New size registration

With add_image_size() you can register a new size and then get it by key:

// let's say in functions.php we register the additional size like this:
add_image_size( 'spec_thumb', 360, 240, true );

// then in the loop output this size as follows:
the_post_thumbnail( 'spec_thumb' );
0

#5 Using $attr argument

An example of the attr argument using an array can be seen below:

the_post_thumbnail( 'post-thumbnail', [ 
	'class' => 'img-responsive responsive--full', 
	'title' => 'Feature image',
] );

Using the array’s keys and values to populate different attributes. You can use this to add classes to the post thumbnail.

Disable lazy loading where this post thumbnail is displayed Introduce in WordPress 5.5.:
the_post_thumbnail( 'post-thumbnail', [ 'loading' => false ] ); 
Set 'sizes' attribute

If you are worried about the sizes attributes are too big for your usage, you can do something like this :

the_post_thumbnail( 'large', [ 'sizes' => '(max-width:320px) 145px, (max-width:425px) 220px, 500px' ] );

The 'sizes' array consists of media queries, so the first parameter is your media query, and the second if what size-width image, should be rendered at that viewportsize. the last parameter is the default size if none of the given media-queries applies.

Useful if you use a column-based grid, where you don’t want the image to be rendered 100vw on smaller viewports.

0

#6 Remove width and height attributes

If you’d like to remove the hardcoding of the ‘height’ and ‘width’ attributes on thumbnail images, which will often effect adaptive/responsive/fluid CSS stylesheets, you can add this snippet to your functions.php:

// remove width & height attributes from images

add_filter( 'post_thumbnail_html', 'remove_img_attr' );

function remove_img_attr( $html ) {
	return preg_replace( '/(width|height)="\d+"\s/', '', $html );
}

Notes

Changelog

Since 2.9.0 Introduced.

the_post_thumbnail() code WP 6.5.4

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