Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →get_the_post_thumbnail() returns a post’s featured image as an HTML string; it does not print the markup. Pass it a post ID or object, an image size, and optional image attributes. Use the returned string when you need to store or modify the markup before output. For direct display in a template, the_post_thumbnail() is usually the simpler choice.
What get_the_post_thumbnail() returns
The function signature is:
get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' )It returns an HTML string for the post’s featured image, normally an <img> element with WordPress-generated attributes such as its source and alternative text. The arguments are optional: omit them to use the global post, the post-thumbnail size, and default attributes.
$post: a post ID, aWP_Postobject, ornull. When it isnull, WordPress uses the global post.$size: a registered image-size name or a width-and-height array.$attr: image attributes, supplied as an associative array or a query-string-style value.
If WordPress cannot retrieve the post or that post has no featured image, the function returns an empty string. It does not generate an image from the post content or choose an arbitrary attachment as a fallback.
Enable featured images in the theme
A theme must declare support for post thumbnails for the featured-image interface and related functionality to be available. Put the declaration in the theme setup callback, commonly attached to after_setup_theme:
function freedom251_theme_setup() {
add_theme_support( 'post-thumbnails' );
}
add_action( 'after_setup_theme', 'freedom251_theme_setup' );The setup hook matters: the function reference specifies that theme support attached to a hook must be registered before init. after_setup_theme is the usual place to do it.
Limit support to selected post types
If featured images should be enabled only for particular post types, pass their names instead of enabling support globally:
function freedom251_theme_setup() {
add_theme_support( 'post-thumbnails', array( 'post', 'page' ) );
}
add_action( 'after_setup_theme', 'freedom251_theme_setup' );Use the post-type names your site actually registers. A custom post type may need to declare thumbnail support in its own registration configuration as well; theme support and the post type’s supported features both affect whether the editor offers the control.
Choose the image size
The default argument is post-thumbnail. WordPress Developer Resources distinguishes this special theme image size from thumbnail, the size managed in Media Settings. Despite their similar names, they are not interchangeable defaults.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
Use an available registered size
Common size names include thumbnail, medium, medium_large, large, and full. The actual dimensions and availability can vary because settings and theme registrations determine the sizes on a site. A named size is often the clearest choice in a theme because the name expresses the intended role:
$image_html = get_the_post_thumbnail( $post_id, 'medium' );Define a theme-specific size
Register a size when a design needs a consistent purpose-built crop, such as a card image. The following setup defines a cropped 640-by-360 size and then requests it:
function freedom251_theme_setup() {
add_theme_support( 'post-thumbnails' );
add_image_size( 'article-card', 640, 360, true );
}
add_action( 'after_setup_theme', 'freedom251_theme_setup' );
$image_html = get_the_post_thumbnail( $post_id, 'article-card' );To configure the special post-thumbnail size rather than add another named size, use set_post_thumbnail_size() in theme setup. Its crop setting can disable cropping, use a centered crop, or specify horizontal and vertical crop positions. Changing a registered size does not resize image files already uploaded. If older uploads need newly generated derivatives at that size, regenerate their thumbnails using an appropriate site workflow.
Request dimensions for one call
A width-and-height array requests dimensions without introducing a named size:
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
$image_html = get_the_post_thumbnail( $post_id, array( 640, 360 ) );Use a named registered size for a reusable theme role; use an array when a one-off dimension request is more suitable. The files available and the resulting image selection still depend on the site’s generated image sizes.
Return markup, print markup, or get only the URL
| Need | Use | Result |
|---|---|---|
| Store, inspect, or compose featured-image HTML | get_the_post_thumbnail() |
Returns an HTML string. |
| Print the featured image in the current template | the_post_thumbnail() |
Echoes the markup returned by get_the_post_thumbnail(). |
Obtain the image URL rather than an <img> element |
get_the_post_thumbnail_url() |
Returns the URL for the requested thumbnail size. |
For example, a card template may need to keep the image HTML in a variable while assembling its markup:
<?php
$post_id = get_the_ID();
$image_html = get_the_post_thumbnail(
$post_id,
'article-card',
array( 'class' => 'article-card__image' )
);
if ( $image_html !== '' ) : ?>
<article class="article-card">
<a href="<?php echo esc_url( get_permalink( $post_id ) ); ?>">
<?php echo $image_html; ?>
<h2><?php echo esc_html( get_the_title( $post_id ) ); ?></h2>
</a>
</article>
<?php endif; ?>This example uses the returned image markup as generated by WordPress and checks that it is non-empty before emitting the card. If the template’s intent is simply to display an image and it needs no intermediate string, use the_post_thumbnail() directly.
When only a URL is needed, use the companion function rather than extracting src from HTML:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match$image_url = get_the_post_thumbnail_url( $post_id, 'large' );Pass image attributes
Use the third argument to add or override image attributes. An associative array is usually easiest to read and maintain:
$image_html = get_the_post_thumbnail(
$post_id,
'medium',
array(
'class' => 'article-card__image',
'alt' => 'A descriptive image alternative',
)
);The function passes the selected attachment, size, and attributes to wp_get_attachment_image(). Attribute handling and the final markup therefore follow WordPress’s attachment-image behavior as well as any filters installed by the site. Choose alternative text that suits the image’s purpose in context; if it is decorative, do not supply misleading descriptive text merely to fill the attribute.
Handle posts without a featured image
Because a missing thumbnail produces an empty string, decide explicitly how the surrounding template should behave. If the entire image wrapper should disappear, conditionally render it:
<?php
if ( has_post_thumbnail( $post_id ) ) {
echo get_the_post_thumbnail(
$post_id,
'medium',
array( 'class' => 'article-card__image' )
);
}
?>For code that already stores the return value, checking the string also handles the function’s empty result:
$image_html = get_the_post_thumbnail( $post_id, 'medium' );
if ( $image_html !== '' ) {
echo $image_html;
}Use has_post_thumbnail() when the decision is about whether the post has a featured image. Checking the returned string is useful when the markup itself is already in hand. Neither approach supplies a fallback automatically; if the design requires a placeholder, implement that behavior separately.
Hooks that can change the requested size or HTML
Theme and plugin developers can alter thumbnail retrieval through these hooks:
post_thumbnail_sizefilters the requested size before the attachment image is generated.post_thumbnail_htmlfilters the resulting thumbnail HTML, allowing the final markup to be changed.begin_fetch_post_thumbnail_htmlandend_fetch_post_thumbnail_htmlfire around thumbnail retrieval and can be used to coordinate behavior during that process.
These hooks can affect output beyond an individual call. If a size or markup looks unexpected, check whether the theme or an active plugin registers a callback on the relevant filter. Prefer a narrowly scoped callback and remove it when it is no longer needed; broad changes to thumbnail HTML can affect multiple templates.
Common problems and fixes
| Symptom | Likely cause | What to check |
|---|---|---|
| No featured-image control in the editor | Theme support or post-type support is missing. | Confirm add_theme_support( 'post-thumbnails' ) runs on after_setup_theme, and verify the relevant post type supports thumbnails. |
| The function returns an empty string | The post could not be resolved, or it has no featured image. | Pass a valid post ID or object, check the global post context when using null, and test with has_post_thumbnail(). |
| The image uses an unexpected size | The requested size is not the one assumed, or a filter changes it. | Pass the intended registered name or dimensions and inspect callbacks on post_thumbnail_size. |
| A custom size does not appear as expected on older uploads | Existing files do not have a derivative for the changed size. | Regenerate thumbnails for existing media after changing or adding a size. |
| The output contains different markup than expected | Attachment-image behavior or a filter modifies the HTML. | Inspect the supplied attributes and callbacks on post_thumbnail_html. |
For visual checks of a rendered page
get_the_post_thumbnail() builds markup; it does not capture a screenshot of the page. If you also need a rendered visual check of a WordPress template, ScreenshotNeo is a separate website screenshot API and MCP server for developers, not a replacement for this PHP function. Its clean-shot process accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with page-verdict and billing information in response headers. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.
Or skip the browser setup
After your theme is running on a reachable URL, one GET request can capture its rendered page. See the ScreenshotNeo API documentation for the request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFor this request, replace the target URL with your page’s URL. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Can I pass a WP_Post object instead of an ID?
Yes. The first argument accepts a post ID, a WP_Post object, or null for the global post.
Does get_the_post_thumbnail() return the image URL?
No. It returns image HTML. Use get_the_post_thumbnail_url() when you need the URL.
Recommended Free Tools
Can I use this function outside the WordPress loop?
Yes, provided you pass a post ID or WP_Post object that WordPress can retrieve. Passing null relies on the global post.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
