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

Display the post thumbnail.


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.

See also See also


Top ↑

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


Top ↑

Source Source

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

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

Top ↑

Changelog Changelog

Changelog
Version Description
2.9.0 Introduced.

Top ↑

More Information More Information

Top ↑

Usage Usage

the_post_thumbnail( $size, $attr );


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by shramee

    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

  2. Skip to note 2 content
    Contributed by sheepysheep60

    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.

  3. Skip to note 3 content
    Contributed by Barbara Ford

    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. Skip to note 4 content
    Contributed by Barbara Ford

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

  5. Skip to note 5 content
    Contributed by Barbara Ford

    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. Skip to note 6 content
    Contributed by brettalton

    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
    //
    function remove_img_attr ($html)
    {
        return preg_replace('/(width|height)="\d+"\s/', "", $html);
    }
    
    add_filter( 'post_thumbnail_html', 'remove_img_attr' );
  7. Skip to note 9 content
    Contributed by jesperstender

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

    the_post_thumbnail( 'large', array( '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.

  8. Skip to note 10 content
    Contributed by Barbara Ford

    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()
    		);
    	}
    }
    

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