_wp_post_thumbnail_html( int|null $thumbnail_id = null, int|WP_Post|null $post = null ): string

Returns HTML for the post thumbnail meta box.

Parameters

$thumbnail_idint|nulloptional
Thumbnail attachment ID.

Default:null

$postint|WP_Post|nulloptional
The post ID or object associated with the thumbnail. Defaults to global $post.

Default:null

Return

string The post thumbnail HTML.

Source

function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
	$_wp_additional_image_sizes = wp_get_additional_image_sizes();

	$post               = get_post( $post );
	$post_type_object   = get_post_type_object( $post->post_type );
	$set_thumbnail_link = '<p class="hide-if-no-js"><a href="%s" id="set-post-thumbnail"%s class="thickbox">%s</a></p>';
	$upload_iframe_src  = get_upload_iframe_src( 'image', $post->ID );

	$content = sprintf(
		$set_thumbnail_link,
		esc_url( $upload_iframe_src ),
		'', // Empty when there's no featured image set, `aria-describedby` attribute otherwise.
		esc_html( $post_type_object->labels->set_featured_image )
	);

	if ( $thumbnail_id && get_post( $thumbnail_id ) ) {
		$size = isset( $_wp_additional_image_sizes['post-thumbnail'] ) ? 'post-thumbnail' : array( 266, 266 );

		/**
		 * Filters the size used to display the post thumbnail image in the 'Featured image' meta box.
		 *
		 * Note: 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.
		 *
		 * @since 4.4.0
		 *
		 * @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          $thumbnail_id Post thumbnail attachment ID.
		 * @param WP_Post      $post         The post object associated with the thumbnail.
		 */
		$size = apply_filters( 'admin_post_thumbnail_size', $size, $thumbnail_id, $post );

		$thumbnail_html = wp_get_attachment_image( $thumbnail_id, $size );

		if ( ! empty( $thumbnail_html ) ) {
			$content  = sprintf(
				$set_thumbnail_link,
				esc_url( $upload_iframe_src ),
				' aria-describedby="set-post-thumbnail-desc"',
				$thumbnail_html
			);
			$content .= '<p class="hide-if-no-js howto" id="set-post-thumbnail-desc">' . __( 'Click the image to edit or update' ) . '</p>';
			$content .= '<p class="hide-if-no-js"><a href="#" id="remove-post-thumbnail">' . esc_html( $post_type_object->labels->remove_featured_image ) . '</a></p>';
		}
	}

	$content .= '<input type="hidden" id="_thumbnail_id" name="_thumbnail_id" value="' . esc_attr( $thumbnail_id ? $thumbnail_id : '-1' ) . '" />';

	/**
	 * Filters the admin post thumbnail HTML markup to return.
	 *
	 * @since 2.9.0
	 * @since 3.5.0 Added the `$post_id` parameter.
	 * @since 4.6.0 Added the `$thumbnail_id` parameter.
	 *
	 * @param string   $content      Admin post thumbnail HTML markup.
	 * @param int      $post_id      Post ID.
	 * @param int|null $thumbnail_id Thumbnail attachment ID, or null if there isn't one.
	 */
	return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID, $thumbnail_id );
}

Hooks

apply_filters( ‘admin_post_thumbnail_html’, string $content, int $post_id, int|null $thumbnail_id )

Filters the admin post thumbnail HTML markup to return.

apply_filters( ‘admin_post_thumbnail_size’, string|int[] $size, int $thumbnail_id, WP_Post $post )

Filters the size used to display the post thumbnail image in the ‘Featured image’ meta box.

Changelog

VersionDescription
2.9.0Introduced.

User Contributed Notes

  1. Skip to note 2 content

    The _wp_post_thumbnail_html function is responsible for generating HTML markup for post thumbnails, often known as featured images. Let’s get into the specifics of what this function can do:

    wp_get_additional_image_sizes() retrieves additional image sizes and puts them in $_wp_additional_image_sizes. This provides flexibility in dealing with different image dimensions.

    This get_post($post) function gets information about the current post and the post type object using get_post_type_object($post->post_type). This provides the structure for explaining the featured image within the context of the selected post type.

    $set_thumbnail_link function creates a link that is in charge of setting the post thumbnail. This link is contained within a paragraph and contains an ID, URL, and caption for modifying the featured image. It is intended to work in combination with the Thickbox JavaScript library to provide a user-friendly interface.

    When a post has a thumbnail attached, the wp_get_attachment_image() function comes into play by providing the necessary HTML code. A key benefit of this function is its ability to let developers adjust the size of the displayed image within the admin interface using suitable filters.

    When a thumbnail is present, the $_wp_additional_image_sizes function goes the extra mile by appending descriptive components to the output. These include helpful directives for editing or upgrading the image, as well as a convenient removal link for the featured image. This enriches the overall user experience.

    In order to smooth the submission process of thumbnail-related data with each post, the function expertly creates a hidden input field. This field expertly stores the thumbnail ID, guaranteeing its connection to the proper post.

    Developers can easily customize the generated HTML markup to meet their specific needs by using the Admin_post_thumbnail_html filter, providing a high level of flexibility and personalization.

    Lastly, this function can be seen as the unsung hero working tirelessly in the background, carefully managing post thumbnails to guarantee their aesthetic appeal, adaptability to different post formats, and ultimately creating a superior experience for both users and developers.

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