get_the_post_thumbnail_url( int|WP_Post $post = null, string|int[] $size = ‘post-thumbnail’ ): string|false

Returns the post thumbnail URL.

Parameters

$postint|WP_Postoptional
Post ID or WP_Post object. Default is global $post.

Default:null

$sizestring|int[]optional
Registered image size to retrieve the source for or a flat array of height and width dimensions. Default 'post-thumbnail'.

Default:'post-thumbnail'

Return

string|false Post thumbnail URL or false if no image is available. If $size does not match any registered image size, the original image URL will be returned.

Source

function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
	$post_thumbnail_id = get_post_thumbnail_id( $post );

	if ( ! $post_thumbnail_id ) {
		return false;
	}

	$thumbnail_url = wp_get_attachment_image_url( $post_thumbnail_id, $size );

	/**
	 * Filters the post thumbnail URL.
	 *
	 * @since 5.9.0
	 *
	 * @param string|false     $thumbnail_url Post thumbnail URL or false if the post does not exist.
	 * @param int|WP_Post|null $post          Post ID or WP_Post object. Default is global `$post`.
	 * @param string|int[]     $size          Registered image size to retrieve the source for or a flat array
	 *                                        of height and width dimensions. Default 'post-thumbnail'.
	 */
	return apply_filters( 'post_thumbnail_url', $thumbnail_url, $post, $size );
}

Hooks

apply_filters( ‘post_thumbnail_url’, string|false $thumbnail_url, int|WP_Post|null $post, string|int[] $size )

Filters the post thumbnail URL.

Changelog

VersionDescription
4.4.0Introduced.

User Contributed Notes

  1. Skip to note 5 content

    Don’t ignore the first parameter.
    Proper usage of `get_the_post_thumbnail_url() ` inside the loop:

    if ( have_posts() ) {
        while ( have_posts() ) {
            the_post();
      
            /* grab the url for the full size featured image */
            $featured_img_url = get_the_post_thumbnail_url(get_the_ID(),'full'); 
     
            /* link thumbnail to full size image for use with lightbox*/
            echo '<a href="'.esc_url($featured_img_url).'" rel="lightbox">'; 
                the_post_thumbnail('thumbnail');
            echo '</a>';
        endwhile; 
    endif; 
  2. Skip to note 6 content

    It’s worth to note that, if you upload a smaller image (let’s say, a 600px wide) and use this to fetch a specific larger image (let’s say, a 1920px wide for your cover), it will return the original image instead (which is smaller than what you need) instead of returning false.

    If you need to fallback to another image in case the specified file doesn’t exist, you can look into wp_get_attachment_image_src instead, and check for the width or height of the image.

  3. Skip to note 7 content

    Downvoted the example posted from @thelilmercoder as it is not proper usage of this function.

    Proper usage of `get_the_post_thumbnail_url()` inside the loop:

    if ( have_posts() ) {
    	while ( have_posts() ) {
    		the_post();
     
    		/* grab the url for the full size featured image */ 
    		$featured_img_url = get_the_post_thumbnail_url('full'); 
    
    		/* link thumbnail to full size image for use with lightbox*/ 
    		echo '<a href="'.$featured_img_url.'" rel="lightbox">'; 
    			the_post_thumbnail('thumbnail');
    		echo '</a>';
    	endwhile; 
    endif; 

    Proper usage of `get_the_post_thumbnail_url()` outside the loop:

    /* get a specific post object by ID */ 
    $post = get_post(2);
     
    /* grab the url for the full size featured image */ 
    $featured_img_url = get_the_post_thumbnail_url($post->ID, 'full'); 
    
    /* link thumbnail to full size image for use with lightbox*/ 
    echo '<a href="'.$featured_img_url.'" rel="lightbox">'; 
    	the_post_thumbnail('thumbnail');
    echo '</a>';
  4. Skip to note 8 content

    To display the featured image with the alt tag use something like this

    $thumbnail = get_the_post_thumbnail_url();
    
    if ( $thumbnail ) {
    	$alt_text = get_post_meta( $thumbnail->ID, '_wp_attachment_image_alt', true );
    
        if ( ! empty( $thumbnail ) ) {
    		if ( ! empty( $alt_text ) ) {
    			$alt_text = $alt_text;
           } else {
    			$alt_text = __( 'no alt text set', 'textdomain' ); 
           }
    	   echo '';
       }
    }

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