Blog

Updated 15 October 2026 · By Abhilash Sahoo, Founder, Infyways

To get the featured image URL in WordPress, use get_the_post_thumbnail_url(). For the current post, at full size:

<?php echo esc_url( get_the_post_thumbnail_url( get_the_ID(), 'full' ) ); ?>

It returns the image URL as a string, or false when the post has no featured image. Pass a post ID to get the image for any post, and a size name such as 'thumbnail', 'medium', 'large' or 'full' to choose the size.

In short: get_the_post_thumbnail_url( $post, $size ) for the URL, get_post_thumbnail_id() for the attachment ID, wp_get_attachment_image_src() when you also need width and height, and _embed=wp:featuredmedia in the REST API.

How do I get the featured image URL inside the loop?

Call get_the_post_thumbnail_url() without a post argument. It uses the global $post, so it works in single.php, index.php, archive templates and any WP_Query loop. Check has_post_thumbnail() first so you don’t print an empty src:

<?php if ( has_post_thumbnail() ) : ?>
    <img src="<?php echo esc_url( get_the_post_thumbnail_url( null, 'large' ) ); ?>"
         alt="<?php echo esc_attr( get_the_title() ); ?>">
<?php endif; ?>

The signature is get_the_post_thumbnail_url( int|WP_Post|null $post = null, string|int[] $size = 'post-thumbnail' ): string|false. It was introduced in WordPress 4.4.

How do I get the featured image URL by post ID?

Pass the post ID (or a WP_Post object) as the first argument. This works anywhere, including outside the loop, in shortcodes, widgets and REST callbacks:

$post_id = 123;
$url     = get_the_post_thumbnail_url( $post_id, 'full' );

if ( $url ) {
    echo esc_url( $url );
}

If you need the attachment ID instead, use get_post_thumbnail_id( $post_id ). It returns the attachment ID, or false if there is none.

How do I get a specific image size?

The $size argument accepts any registered size name or an array of width and height in pixels:

get_the_post_thumbnail_url( $post_id, 'thumbnail' );    // Settings > Media size
get_the_post_thumbnail_url( $post_id, 'medium_large' ); // 768px wide by default
get_the_post_thumbnail_url( $post_id, 'full' );         // original upload
get_the_post_thumbnail_url( $post_id, array( 600, 400 ) );

The default is 'post-thumbnail', a special size registered when a theme adds post-thumbnail support. It is not the same as the 'thumbnail' size in Settings > Media.

When you also need the width and height, use wp_get_attachment_image_src(). It returns an array: index 0 is the URL, 1 the width, 2 the height, and 3 whether the image is a resized version:

$image = wp_get_attachment_image_src( get_post_thumbnail_id( $post_id ), 'large' );

if ( $image ) {
    list( $url, $width, $height ) = $image;
}

How do I get the featured image URL from the REST API?

Posts in the REST API only include featured_media, the attachment ID. Add _embed=wp:featuredmedia to get the media object in the same request, then read source_url:

GET /wp-json/wp/v2/posts/123?_embed=wp:featuredmedia

fetch( '/wp-json/wp/v2/posts/123?_embed=wp:featuredmedia' )
  .then( ( res ) => res.json() )
  .then( ( post ) => {
    const media = post._embedded?.['wp:featuredmedia']?.[0];
    const url   = media?.source_url;                              // full size
    const thumb = media?.media_details?.sizes?.thumbnail?.source_url;
  } );

If you use _fields to slim the response, include _links and _embedded, or the embed is dropped: ?_embed=wp:featuredmedia&_fields=id,featured_media,_links,_embedded. We tested this on our own site. Without _embed, request /wp-json/wp/v2/media/{featured_media} as a second call.

How do I show the featured image in a block theme?

Block themes don’t use PHP templates for this. Use the Post Featured Image block (core/post-featured-image) inside a single template or a Query Loop. Its settings include the image size (sizeSlug), aspect ratio, whether it links to the post (isLink), and an option to use the first image in the post when no featured image is set (useFirstImageFromPost).

You only need PHP in a block theme when you build a custom block or a render callback. There, get_the_post_thumbnail_url() works the same way.

How do I set a fallback image when there is no featured image?

Because the function returns false when there is no featured image, fall back with a short check:

$url = get_the_post_thumbnail_url( get_the_ID(), 'large' );

if ( ! $url ) {
    $url = get_theme_file_uri( 'assets/images/default-featured.jpg' );
}

In a block theme, the Post Featured Image block’s “use first image from post” option is a no-code alternative.

How do I get the featured image alt text and srcset?

The URL functions return only the URL. The alt text is stored as attachment meta, and srcset is built from the registered sizes:

$thumb_id = get_post_thumbnail_id( $post_id );
$alt      = get_post_meta( $thumb_id, '_wp_attachment_image_alt', true );
$srcset   = wp_get_attachment_image_srcset( $thumb_id, 'large' );
$url      = wp_get_attachment_image_url( $thumb_id, 'large' );

If you just want a complete, responsive <img> tag with alt, srcset and sizes, use get_the_post_thumbnail() or the_post_thumbnail() instead of building it yourself.

Which featured image function should I use?

Signatures checked against the WordPress Code Reference on 15 October 2026.

Why is get_the_post_thumbnail_url() not working?

• The theme has no featured image support. Add it in functions.php: add_action( 'after_setup_theme', function () { add_theme_support( 'post-thumbnails' ); } );. Block themes and most modern themes already have it.
• It returns false. The post has no featured image set, or you are outside the loop without passing a post ID. Use has_post_thumbnail( $post_id ) to check.
• It returns the wrong size. The size name may not be registered, or the image was uploaded before the size existed. Regenerate thumbnails (for example with WP-CLI: wp media regenerate) so the missing sizes are created.
• The URL is the full image instead of the size you asked for. WordPress falls back to a larger file when the requested size does not exist for that image. Regenerate thumbnails or pick a registered size.
• Nothing prints. get_the_post_thumbnail_url() returns a value; it does not echo. Use echo esc_url( ... ).
• The REST response has no _embedded. Add _embed=wp:featuredmedia, and include _links,_embedded if you use _fields.

Frequently asked questions

How do I get the featured image URL in WordPress?

Use get_the_post_thumbnail_url(). Inside the loop call it without arguments; elsewhere pass the post ID, for example get_the_post_thumbnail_url( 123, 'full' ).

What does get_the_post_thumbnail_url() return if there is no featured image?

It returns false, so check the result or call has_post_thumbnail() before printing it.

How do I get the full-size featured image URL?

Pass 'full' as the size: get_the_post_thumbnail_url( $post_id, 'full' ). Without a size it returns the 'post-thumbnail' size.

How do I get the featured image ID?

Use get_post_thumbnail_id( $post_id ). It returns the attachment ID, or false if the post has no featured image.

How do I get the featured image URL in the REST API?

Request the post with ?_embed=wp:featuredmedia and read _embedded['wp:featuredmedia'][0].source_url, or fetch /wp-json/wp/v2/media/{featured_media} separately.

How do I get the featured image width and height?

Use wp_get_attachment_image_src( get_post_thumbnail_id( $post_id ), 'large' ). It returns the URL, width, height and whether the image is resized.

How do I get the featured image alt text?

Read the attachment meta: get_post_meta( get_post_thumbnail_id( $post_id ), '_wp_attachment_image_alt', true ).

Why does my theme not show the Featured Image box?

The theme hasn’t declared support. Add add_theme_support( 'post-thumbnails' ) on the after_setup_theme hook in functions.php.

Updated 16 October 2026 · By Abhilash Sahoo, Infyways

$result = update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' );

What are the parameters of update_post_meta()?

The signature from the official WordPress developer reference is:

update_post_meta( int $post_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' ): int|bool

Internally, update_post_meta() is a thin wrapper: it swaps a revision ID for its parent and then calls update_metadata( 'post', ... ), the same engine behind user, term and comment meta.

What does update_post_meta() return?

Two practical lessons follow. First, don’t treat false as an error: it usually means “nothing to change”. Second, WordPress doesn’t check that the post exists, so validate the ID yourself or you’ll leave orphaned rows in wp_postmeta:

if ( ! get_post( $post_id ) ) {
    return; // avoid orphaned meta
}
$result = update_post_meta( $post_id, 'color', 'blue' );
if ( false === $result && get_post_meta( $post_id, 'color', true ) !== 'blue' ) {
    error_log( 'Saving color failed' ); // a real failure
}

How do I use update_post_meta()? (examples)

Save a custom field on save_post (secure version)

add_action( 'save_post_product', function ( $post_id ) {
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
    if ( wp_is_post_revision( $post_id ) ) return;
    if ( ! isset( $_POST['iw_price_nonce'] ) || ! wp_verify_nonce( $_POST['iw_price_nonce'], 'iw_save_price' ) ) return;
    if ( ! current_user_can( 'edit_post', $post_id ) ) return;

    if ( isset( $_POST['iw_price'] ) ) {
        $price = sanitize_text_field( wp_unslash( $_POST['iw_price'] ) );
        update_post_meta( $post_id, '_iw_price', $price );
    }
} );

$_POST data is already slashed by WordPress, so wp_unslash() it before sanitizing. update_post_meta() then strips slashes again, so plain text values come out right. See the slashing section below for the case where this goes wrong.

Read the value back

$price = get_post_meta( $post_id, '_iw_price', true ); // single value (string)

Change a page template

update_post_meta( $page_id, '_wp_page_template', 'templates/full-width.php' );

Increment a counter

$views = (int) get_post_meta( $post_id, 'iw_views', true );
update_post_meta( $post_id, 'iw_views', $views + 1 );

Under heavy traffic, two requests can read the same number and both write +1. For accurate counters, use a custom table or an atomic SQL UPDATE.

How does the $prev_value parameter work?

A post can hold several rows with the same key (added with add_post_meta()). $prev_value picks which one to change:

That last row is the classic bug: calling update_post_meta() without $prev_value on a multi-value key silently destroys the other values.

Unique vs multiple values: add_post_meta() and get_post_meta()

Because a missing key returns '', you can’t tell “empty” from “not set” with get_post_meta() alone. Use metadata_exists( 'post', $post_id, $key ).

What happens when you save an array?

WordPress serializes arrays and objects on save and unserializes them on read. The real stored value for [12, 15, 18] is a:3:{i:0;i:12;i:1;i:15;i:2;i:18;}.

• get_post_meta( $p, 'gallery', true ) returns the array. With false you get it nested one level deeper ([[12, 15, 18]]), which is a common source of “my array has an extra level” bugs.
• Saving the identical array again returns false. Saving ['12','15','18'] (strings) returns true, because the serialized form differs.
• Scalars come back as strings: 5 → '5', true → '1', false → '' (and the row still exists).
• You can’t query inside serialized data with meta_query reliably. If you need to filter by a value, store it in its own key.

Why do backslashes disappear? (wp_slash and JSON)

For historical reasons, update_post_meta() expects the key and value to be slashed, and runs stripslashes() on them before saving. Our test results:

The rule is simple: if a value can contain a backslash (JSON, Windows paths, regex), wrap it in wp_slash(). Values from $_POST are the exception, since they arrive slashed. wp_unslash() them for sanitizing, and pass the result straight to update_post_meta() only if it contains no backslashes you need to keep.

What are protected meta keys (underscore prefix)?

Keys starting with _ are “protected”: is_protected_meta( '_price', 'post' ) returns true, and is_protected_meta( 'price', 'post' ) returns false. Protected keys are hidden from the classic Custom Fields meta box, so editors can’t change them by accident. That’s why WooCommerce uses _price and core uses _wp_page_template and _thumbnail_id (see our guide to getting the featured image URL in PHP). Protection is about the UI only. It isn’t security, as the REST test below shows.

How do I delete post meta?

To remove a key from every post, use delete_post_meta_by_key( 'tag' ). Don’t set a value to '' when you mean “remove”, because that leaves a row behind.

How do I update post meta through the REST API?

Meta only appears in /wp-json/wp/v2/posts/<id> (and in the block editor) after you register it with show_in_rest:

add_action( 'init', function () {
    register_post_meta( 'post', 'iw_price', array(
        'type'              => 'number',
        'single'            => true,
        'show_in_rest'      => true,
        'sanitize_callback' => fn( $value ) => round( (float) $value, 2 ),
        'auth_callback'     => fn() => current_user_can( 'edit_posts' ),
    ) );
    register_post_meta( 'post', 'iw_tags', array(
        'type'         => 'array',
        'single'       => true,
        'show_in_rest' => array( 'schema' => array( 'items' => array( 'type' => 'string' ) ) ),
    ) );
} );

Then send POST /wp-json/wp/v2/posts/4 with {"meta":{"iw_price":19.999,"iw_tags":["a","b"]}}. What we saw:

Three gotchas here that most tutorials miss:

• auth_callback protects writes, not reads. Never register a secret with show_in_rest.
• WordPress passes 4 arguments to sanitize_callback, and strict PHP built-ins like floatval crash. Wrap them in a closure.
• The sanitize_callback also runs on direct PHP calls. Our update_post_meta( 4, 'iw_price', '7.456abc' ) was stored as '7.46'.

Site-wide settings work the same way through register_setting(). See our WordPress get_option() guide for the REST settings endpoint.

Is update_post_meta() slow? (meta cache and performance)

WordPress loads all meta for a post in one query and keeps it in the object cache. We counted $wpdb->num_queries:

• When you loop over IDs you fetched yourself, prime the cache with update_meta_cache( 'post', $ids ). WP_Query does this for you by default (update_post_meta_cache).
• Each changed update_post_meta() clears that post’s meta cache. In bulk imports, compare values first or batch your writes.
• wp_postmeta has no index on meta_value, so meta_query filters on large sites get slow. Use a taxonomy or a custom table for data you filter on heavily.
• On a case-insensitive collation (the default, utf8mb4_unicode_520_ci), update_post_meta( $p, 'color2', 'Y' ) updated our existing Color2 row, but get_post_meta( $p, 'color2', true ) returned ''. Keep keys lowercase.

Which hooks fire when post meta is updated?

update_post_meta vs add_post_meta vs update_metadata

What are the most common update_post_meta mistakes?

1. Treating false as failure. An unchanged value also returns false.
2. Overwriting multi-value keys. Leaving out $prev_value overwrites every row.
3. Breaking JSON. Values with backslashes need wp_slash().
4. Using get_post_meta( ..., false ) for an array. It’s nested one level deeper, so use true.
5. Skipping nonce and capability checks on save_post, and not skipping autosaves.
6. Saving meta for post IDs that don’t exist. WordPress adds the orphan row without complaint.
7. Thinking _keys are private. They’re only hidden from the meta box, and REST can still expose them.
8. Running get_post_meta() in a loop without priming the meta cache.
9. Using built-in PHP functions as sanitize_callback, which causes an ArgumentCountError fatal.

Need the current page’s slug or title before saving meta for it? See how to get the current page name in WordPress.

FAQs

What does update_post_meta return?

The new meta ID (int) if the key didn’t exist, true if an existing value changed, and false on failure or when the new value equals the stored one.

Why does update_post_meta return false?

Most often because the value is identical to what’s stored (including 5 vs "5"). It also returns false for a post ID of 0, an empty key, a $prev_value that doesn’t match, or a filter that blocks the write.

Does update_post_meta create the key if it doesn’t exist?

Yes. It behaves like add_post_meta() and returns the new meta ID.

Does update_post_meta check that the post exists?

No. In our test, update_post_meta( 999999, 'x', 'y' ) returned a meta ID for a post that doesn’t exist. Check with get_post() first.

How do I update only one of several values with the same key?

Pass the current value as the fourth argument: update_post_meta( $id, 'mood', 'excited', 'sad' ).

Can I store an array with update_post_meta?

Yes. WordPress serializes it automatically. Read it back with get_post_meta( $id, $key, true ).

Why are backslashes removed from my meta value?

update_post_meta() runs stripslashes() on input. Wrap the value in wp_slash() to keep backslashes in JSON or file paths.

What is the difference between update_post_meta and add_post_meta?

update_post_meta() adds or overwrites. add_post_meta() always adds a new row, unless $unique is true and the key already exists.

How do I update post meta via the REST API?

Register the key with register_post_meta() and show_in_rest => true, then send {"meta":{"key":"value"}} to /wp-json/wp/v2/posts/<id> as an authenticated user. Unregistered keys are ignored.

Does update_post_meta work on revisions?

If you pass a revision ID, the meta is saved on the parent post. In our test, the revision itself got nothing.

Is calling get_post_meta many times slow?

Not for one post. All its meta loads in one query and is then cached. Across many posts, prime the cache with update_meta_cache(), or let WP_Query do it.

Conclusion

update_post_meta() is simple to call but easy to misuse. Treat false as “maybe unchanged”, use $prev_value for multi-value keys, wp_slash() anything with backslashes, register keys before using them over REST, and prime the meta cache in loops. If you’d rather have a team build custom fields, meta boxes or a full plugin for you, our WordPress plugin development service can help.

When you visit a website, you often see a bunch of words or tags grouped together, right?
These are called tag clouds. They help you find the most popular topics on the website and make it easy for you to explore different content. But sometimes, the tag clouds in WordPress, a popular website-making tool, aren’t very good.
Don’t worry, though! This guide will teach you how to make better tag clouds that will make your website visitors happy.

What Are Tag Clouds?

Tag clouds are like signposts on a website. They help you navigate through all the content available. The more a tag is used, the bigger or brighter it appears in the tag cloud. This way, visitors can easily find and explore topics they’re interested in.

Think of your website as a huge library, and the tag cloud as the index. Just by looking at the tag cloud, users can find popular topics and dive into the content they like. Tag clouds give your audience the freedom to explore without feeling lost.

What Makes Up a Tag Cloud?

A tag cloud is made up of tags, which are clickable links. They are displayed in different sizes or colors based on how important they are. The size or color shows how often the tags are used, helping users explore content easily.

Why Good Tag Cloud Design Matters

Organizing Tags

To make a better tag cloud, you need to sort your tags properly. Group them based on topics or how related they are. This will make your tag cloud easier to use.

Making Tag Clouds User-Friendly

The best websites focus on user experience. When you design your tag cloud, make sure it’s easy to use on all devices and screen sizes. This way, everyone can have a great experience, no matter what device they use.

Making Tag Clouds Look Good

A good-looking tag cloud can make users want to explore more. Try using cool fonts, bright colors, and nice layouts. This will make users want to click on the tag cloud and explore your content.

How to Build Better WordPress Tag Clouds

Picking the Right Plugin

WordPress has many tag cloud plugins. Choose one that helps you reach your goals and lets you customize your tag cloud. Plugins like “Tag Cloud Magic” or Cool Tag Cloud let you control how your tag cloud looks and works.

Adjusting Tag Cloud Settings

Changing the tag cloud settings can help it match your website’s look and goals. You can change things like font size, color scheme, and how many tags are shown to make your tag cloud look good and easy to use.

Making Tag Clouds Work on All Devices

More people are using their phones to browse the web. So, it’s important to make sure your tag cloud looks good on all devices. Use responsive design techniques to make tag clouds that work well on different screen sizes.

Adding Fun Visuals

Tag clouds don’t have to be boring. Add fun visuals like icons, pictures, or custom images as tags. This will make your tag cloud more interesting and inviting.

Best Practices for Tag Clouds

Creating a Good Tag Structure

A well-organized tag cloud needs a good tag structure. Look at your content and find common themes or categories. Create a logical structure that helps users navigate.

Grouping Tags

Tags work even better when they’re grouped into categories. For example, if you have a food blog, you could create categories like “desserts,” “main courses,” or “vegetarian.” This helps users find specific content easily.

Being Consistent and Avoiding Duplicate Tags

Make sure you use tags consistently across your content. Don’t use synonyms or similar terms as separate tags. This makes it easier for users to find what they’re looking for.

Updating Tags

Over time, you might end up with tags that you don’t use anymore. Regularly check your tag cloud and remove or combine tags that are too similar. This keeps your tag cloud up-to-date and accurate.

Advanced Tips for Improving Tag Clouds

Using SEO

SEO, or Search Engine Optimization, helps your website show up in search results. Use relevant keywords in your tags and their descriptions to improve your website’s visibility. A well-optimized tag cloud can help your SEO efforts.

Using Plugins for Customization and Optimization

Plugins can be really helpful for customizing and optimizing your tag cloud. Try plugins like “Tag Manager” or “Custom Taxonomies Menu Widget” to unlock more customization options and improve user experience.

Using Widgets

Widgets let you show your tag cloud in different places on your website. Try putting the tag cloud in easy-to-find areas, like the sidebar or footer. This encourages users to engage and explore.

Linking Tag Clouds to Related Content

Link your tag cloud to related content on your website. When users click on a tag, take them to a page that shows related articles or posts. This encourages users to explore more and stay on your site longer.

Making Tag Clouds More Interactive

Adding Filtering and Sorting Options

Let users filter or sort tags based on what they want. Add options like alphabetical sorting, popularity sorting, or category filtering. This lets users customize their exploration experience.

Adding a Search Feature

Make it easier for users by adding a search feature to your tag cloud. This lets users search for specific tags and find relevant content quickly.

Using Tooltips

Tooltips give users more information about tags. When users hover over a tag, show a tooltip with a brief description or related stats. This makes the user experience better and encourages users to engage more.

Adding Animations

Animations can make a lasting impression. Consider adding subtle animations or hover effects to your tag cloud. These small interactions make your tag cloud more fun and interesting.

How to Measure Tag Cloud Performance

Analyzing User Interactions

Use tools like Google Analytics to track how users interact with your tag cloud. Look at things like how often users click on tags, how long they spend exploring tags, and which tags get the most clicks. This can help you understand user engagement and make improvements.

Tracking Click-through Rates

Find out which tags are popular by tracking how often they’re clicked. Use this data to make popular tags more noticeable. This attracts user attention and encourages them to explore more.

Using Analytics Tools

Use analytics tools designed for tag clouds, like “Tag Cloud Analyzer” or “Tag Manager Analytics.” These tools give you detailed insights into how your tag cloud is performing and how users are interacting with it.

Conclusion

Improving WordPress tag clouds is a journey. By understanding what tag clouds are, using best practices, and trying out advanced techniques, you can make your tag cloud a powerful tool that makes your website visitors happy.