the_post_thumbnail( string|array $size = 'post-thumbnail', string|array $attr = '' )
Display the post thumbnail.
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
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: ''
Source
File: wp-includes/post-thumbnail-template.php
function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
echo get_the_post_thumbnail( null, $size, $attr );
}
Changelog
| Version | Description |
|---|---|
| 2.9.0 | Introduced. |
More Information
Usage
the_post_thumbnail( $size, $attr );
Post thumbnail sizes:
Hard cropped sizes have fixed height and width
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.
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:
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 );Expand full source codeCollapse full source code
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():Register new image sizes for Post Thumbnails with: add_image_size().
To set the default size for Post Thumbnails see: set_post_thumbnail_size().
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:
You can also give Post Thumbnails their own class.
Display the Post Thumbnail with a class “alignleft”:
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' );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().
$attr:$attr = array( 'src' => $src, 'class' => "your-css-class", 'alt' => "your alt text" );If you are worried about the sizes attributes are too big for your usage, you can do something like this :
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.
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() ); } }See Also:
get_the_post_thumbnail()