get_the_post_thumbnail( int|WP_Post $post = null, string|int[] $size = 'post-thumbnail', string|array $attr = '' ): string
Retrieves the post thumbnail.
Contents
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.
Parameters
-
$post
int|WP_Post Optional -
Post ID or WP_Post object. Default is global
$post
.Default:
null
-
$size
string|int[] Optional -
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default
'post-thumbnail'
.Default:
'post-thumbnail'
-
$attr
string|array Optional -
Query string or array of attributes.
Default:
''
Return
string The post thumbnail image tag.
More Information
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
.
Source
File: wp-includes/post-thumbnail-template.php
.
View all references
function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
$post = get_post( $post );
if ( ! $post ) {
return '';
}
$post_thumbnail_id = get_post_thumbnail_id( $post );
/**
* Filters the post thumbnail size.
*
* @since 2.9.0
* @since 4.9.0 Added the `$post_id` parameter.
*
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param int $post_id The post ID.
*/
$size = apply_filters( 'post_thumbnail_size', $size, $post->ID );
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 int $post_id The post ID.
* @param int $post_thumbnail_id The post thumbnail ID.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
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 int $post_id The post ID.
* @param int $post_thumbnail_id The post thumbnail ID.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );
} else {
$html = '';
}
/**
* Filters the post thumbnail HTML.
*
* @since 2.9.0
*
* @param string $html The post thumbnail HTML.
* @param int $post_id The post ID.
* @param int $post_thumbnail_id The post thumbnail ID, or 0 if there isn't one.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
* @param string|array $attr Query string or array of attributes.
*/
return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
}
Hooks
-
do_action( 'begin_fetch_post_thumbnail_html',
int $post_id ,int $post_thumbnail_id ,string|int[] $size ) -
Fires before fetching the post thumbnail HTML.
-
do_action( 'end_fetch_post_thumbnail_html',
int $post_id ,int $post_thumbnail_id ,string|int[] $size ) -
Fires after fetching the post thumbnail HTML.
-
apply_filters( 'post_thumbnail_html',
string $html ,int $post_id ,int $post_thumbnail_id ,string|int[] $size ,string|array $attr ) -
Filters the post thumbnail HTML.
-
apply_filters( 'post_thumbnail_size',
string|int[] $size ,int $post_id ) -
Filters the post thumbnail size.
Changelog
Version | Description |
---|---|
4.4.0 | $post can be a post ID or WP_Post object. |
2.9.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
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:
You can also give Post Thumbnails their own class:
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()
:Register new image sizes for Post Thumbnails with:
add_image_size()
.To set the default size for Post Thumbnails see:
set_post_thumbnail_size()
.Sample Usage
Post Thumbnail Linking to the Post Permalink
This example shows the 5 latest Post Thumbnails linked to their Post permalink.
Remove width and height attributes from the returning html
get_the_post_thumbnail
function produces html withimg
tag which includes width, height, src, class, alt and title attributes. The following code snippet is useful if someone wish to remove width and height attribute.This function provides
'post_thumbnail_html'
filter before returning the html.You can set more than just classes –
If you want to optimize your SrcSet values you can do something like this
etc.
Normally in a grid, the srcset can go 100vw – which is sometimes way too big –
this method lets you control that.
Top ↑
Feedback
Great trick! I would otherwise have to use the `wp_calculate_image_sizes` filter – which doesn’t support attributes/extra hints yet (though planned to be released for the near future). — By strarsis —
Post Thumbnail Linking to large Image Size
This example links to the “large” Post Thumbnail image size and must be used within The Loop.
See Also:
the_post_thumbnail()
Post thumbnails in a listing context are often linked to the content they’re representing. Instead of adding that every time, here is a filter you can add that will do it automatically based on an `$attr` passed in.
Just “add the above to your functions.php file” (there’s probably a better place for it) and use it like this in a template file:
To give class to the featured image post thumbnail
To get full featured image
Top ↑
Feedback
Thank you very much! — By joaodiasjr —