The wp_get_attachment_image Function Makes WordPress Image Output Cleaner & More Reliable

Images do a lot of work on a WordPress site. They carry your brand, explain your content, and shape how a page feels. Sadly, many developers still paste image URLs directly into their templates, which breaks the first time a file moves or a layout changes.

There’s a cleaner way. The wp_get_attachment_image function pulls an image from your Media Library and returns a full, ready-to-use HTML image tag. The correct sizes and attributes are already filled in.

In this guide, we show you what the function does and how each part works. You’ll also see how to safely display images from posts, custom fields, and dynamic layouts, keeping them fast and accessible. To follow along, you should be comfortable editing PHP in a child theme before you start.

KEY TAKEAWAYS

• wp_get_attachment_image returns a complete, ready-to-use HTML image tag from a Media Library attachment ID.
• It needs a valid attachment ID. Otherwise nothing displays on the page.
• It adds responsive srcset, sizes, lazy loading, and async decoding for you, with no extra markup.
• Register it as a shortcode in functions.php and return the output instead of echoing it.
• It works with get_post_meta() and ACF to display images stored in custom fields.

What Is the wp_get_attachment_image Function?

The wp_get_attachment_image function is built into WordPress. You provide it with the ID of an image in your Media Library, and it offers a complete HTML <img> tag back. The tag already has the source, size class, alt text, and responsive details filled in.

The simplest form is:

echo wp_get_attachment_image( $attachment_id, 'medium' );

This grabs the image with that ID and prints its medium version, wrapped in proper HTML. You don’t write the <img> tag yourself. WordPress builds it from what it knows about the file. That’s the point of wp_get_attachment_image in WordPress. It offers less manual markup, and output that stays in step with your Media Library.

What Is a WordPress Image Attachment & Attachment ID?

Every time you upload a file to WordPress, it becomes an attachment. An attachment is a small post that sits behind the scenes.

It holds the file and details about it:

• alt text.
• Caption.
• Description.
• Available sizes.
• File URLs.

Each attachment has its own number, called the attachment ID.

That WordPress image attachment ID is how the function finds your file. Provide the correct ID, and WordPress can look up everything it needs. However, if you give the wrong one, you get nothing back.

To find an attachment ID in the WordPress dashboard:

• Go to Media → Library.
• Click an image to open it.
• Look at the URL of the edit screen:

https://yoursite.co.za/wp-admin/upload.php?item=60

Here, 60 is the attachment ID.

There is one point that trips people up often. An attachment ID is not the same as a post or page ID. A blog post has its own ID. The image inside it has a different one. Mixing up the two is a common cause of images not appearing. When you work with a WordPress attachment image, always check that the ID belongs to the file, not the post it lives on.

Why Use It Instead of Hardcoding an Image URL?

When you paste a fixed image URL into a template, you may run into trouble down the road. For example, if the file is renamed, moved, or replaced, every hardcoded link to it breaks. You will then hunt through templates to fix them by hand.

However, the wp_get_attachment_image function avoids all of that. Here’s what you gain when you display Media Library images in WordPress correctly:

• It uses your registered image sizes, so you serve the right size for the spot.
• It writes responsive markup for you, so browsers can choose the best file for each screen.
• It adds lazy loading and async decoding on its own, which helps pages load sooner.
• It keeps the output tied to the Media Library, so updates flow through automatically.
• It cuts template upkeep, because you’re not managing raw URLs.
• It allows you to add classes and other attributes cleanly.

That last point matters most on real sites. Many of your visitors in South Africa browse on phones and mobile data. Serving a smaller, well-chosen image saves them time and money, and it keeps your pages quick. A hardcoded URL can’t do any of that for you.

Function Syntax & Parameters

Here is the full shape of the function:

wp_get_attachment_image(
   int $attachment_id,
    string|int[] $size = 'thumbnail',
    bool $icon = false,
    string|array $attr = ''
);

It takes four inputs and returns an HTML string. Only the first parameter is required. Let’s go through each:

$attachment_id (required)

This is the ID of the image you wish to show. It must be a real attachment ID from your Media Library. If it’s missing or incorrect, the function returns an empty result, and no image appears. This is the one input you cannot skip.

$size (optional)

This sets which size WordPress serves. You can use the built-in names:

• thumbnail (default value).
• medium.
• large.
• full.

You can also use a custom size that your theme or a plugin has registered with add_image_size(). If you omit this, WordPress uses thumbnail. If you name a size that doesn’t exist, WordPress falls back to a size it does have. Reach for full only when you truly need the original file, as it’s the heaviest option.

$icon (optional)

This decides whether to show a file icon instead of the image. It’s meant for attachments that aren’t images, for example a PDF. It’s false by default, so the real image displays. You rarely change this when you’re working with photos and graphics.

$attr (optional)

This allows you to add attributes to the image tag. You pass an array of name and value pairs. Common ones include class, alt, title, loading, fetchpriority, and decoding.

Here is how that looks:

$attr = array(
    'class' => 'team-photo',
    'alt'   => 'Staff outside the Durban branch',
    'title' => 'Durban team',
);
echo wp_get_attachment_image( $attachment_id, 'medium', false, $attr );

WordPress merges your attributes into the tag it builds. If you don’t pass any, it still adds an empty string by default.

WordPress Image Sizes & Responsive Output

When you upload an image, WordPress doesn’t keep just a single copy; it creates several sizes from the original. A large team photo may be saved as a thumbnail, a medium version, a large version, and the full file. The function serves whichever size you request.

The bigger win is responsive output. Modern browsers can choose the best image for each device if you provide a list to choose from. WordPress builds that list for you. Ask for the full size, and you’ll see this output:

<img width="1280" height="826"
     src="https://yoursite.co.za/wp-content/uploads/2024/10/team-photo.jpg"
     class="attachment-full size-full"
     alt="Our team at the Cape Town office"
     decoding="async"
     fetchpriority="high"
     srcset="https://yoursite.co.za/wp-content/uploads/2024/10/team-photo.jpg 1280w,
    sizes="(max-width: 1280px) 100vw, 1280px">

Look at the srcset and sizes attributes; they tell the browser which files exist and how wide each one is. A phone on a slow connection can download a small file, while a desktop can download a large one. You get these WordPress responsive images without writing a single line of that markup yourself.

How & Where to Add This Code

The examples so far use echo to keep them short. That works inside a theme template file. But editing template files for every image is tricky, and it isn’t an option for everyone. There’s a friendlier way to run the same code. You register it once as a shortcode, then drop that shortcode into any page or post.

To do this, add the PHP to your child theme’s functions.php file. Use a child theme so a theme update won’t wipe your work and never directly edit the parent theme’s files. If you’d rather not touch the theme at all, a small site-specific plugin can do the same thing just as well.

IMPORTANT:

Test on a staging website first, and back up your site before you edit.

One rule is crucial here. A shortcode must return its output, not echo it. If you echo inside a shortcode, the image jumps to the top of the page instead of sitting where you placed the shortcode. Return the HTML, and WordPress places it in the right spot.

This shortcode outputs any image by its ID, with an optional size, class, and alt text:

// Add to your child theme's functions.php
function mysite_attachment_image( $atts ) {
    $atts = shortcode_atts(
        array(
            'id'    => 0,
            'size'  => 'medium',
            'class' => '',
            'alt'   => '',
        ),
        $atts
    );
    if ( ! $atts['id'] ) {
        return '';
    }
    $extra = array();
    if ( $atts['class'] ) {
        $extra['class'] = $atts['class'];
    }
    if ( $atts['alt'] ) {
        $extra['alt'] = $atts['alt'];
    }
    return wp_get_attachment_image( (int) $atts['id'], $atts['size'], false, $extra );
}
add_shortcode( 'attachment_image', 'mysite_attachment_image' );

Save the file. Then, edit any page or post, add a Shortcode block, and type this:

[attachment_image id="282" size="large" class="team-photo" alt="Our team in Cape Town"]

Preview the page, and you’ll see image 282 at the large size, right where the shortcode is located, carrying your class and alt text. If nothing shows, the ID is almost always the reason, so check this first.

Display a Featured Image

Featured images are the classic case. This shortcode shows the featured image of whatever post or page it sits on:

// Add to your child theme's functions.php
function mysite_featured_image( $atts ) {
    $atts = shortcode_atts( array( 'size' => 'large' ), $atts );
    if ( ! has_post_thumbnail() ) {
        return '';
    }
    return wp_get_attachment_image( get_post_thumbnail_id(), $atts['size'] );
}
add_shortcode( 'featured_image', 'mysite_featured_image' );

Use it in the editor:

[featured_image size="large"]

It first checks whether the post has a featured image with has_post_thumbnail(). If it does, it fetches the ID with get_post_thumbnail_id() and returns the image.

Preview the post, and the featured image appears where you placed the shortcode. If the post has no featured image, nothing shows, so you never receive an empty tag. Swap the size for any registered size that suits the spot.

Display All Images Attached to a Post

Sometimes you want every image tied to one post. This shortcode gathers them and returns them as a group:

// Add to your child theme's functions.php
function mysite_post_images( $atts ) {
    $atts = shortcode_atts( array( 'size' => 'thumbnail' ), $atts );
    $images = get_attached_media( 'image', get_the_ID() );
    if ( empty( $images ) ) {
        return '';
    }
    $output = '';
    foreach ( $images as $image ) {
        $output .= wp_get_attachment_image( $image->ID, $atts['size'] );
    }
    return $output;
}
add_shortcode( 'post_images', 'mysite_post_images' );

Add it to a post:

[post_images size="medium"]

The get_attached_media() call collects the images for the current post, and the loop builds a tag for each. Notice that the tags are added to a string and returned together, not echoed.

This is where the return rule earns its place, since echoing in a loop would push every image to the top of the page. One catch: an image only counts as attached if it was uploaded directly to that post. Many library images aren’t attached this way, so this displays only the ones that are linked.

In this case, the output is one <img> tag for every image attached to the current post, printed one after another. Each tag is a full WordPress <img>, the same kind the other shortcodes produce, with the source, width, height, class, alt text, and responsive srcset and sizes filled in.

They appear at the size you asked for (medium, in [post_images size=”medium“]), in the order the images are attached to the post.

Display Images Stored in Custom Fields

Custom fields are how much of the dynamic content works. A field may hold a service image, a speaker photo, or a product shot.

An image is stored in a field in one of two ways:

1. It’s either saved as an attachment ID.
2. Or it’s saved as an image URL.

How you handle it depends on which one you have.

When the Field Stores an Attachment ID

This is the easy case. Read the field with get_post_meta(), then pass the ID to the function. The shortcode takes the field name, so you can reuse it for any field:

// Add to your child theme's functions.php
function mysite_field_image( $atts ) {
    $atts = shortcode_atts(
        array(
            'key'  => '',
            'size' => 'medium',
        ),
        $atts
    );
    if ( ! $atts['key'] ) {
        return '';
    }
    $attachment_id = get_post_meta( get_the_ID(), $atts['key'], true );
    if ( ! $attachment_id ) {
        return '';
    }
    return wp_get_attachment_image( (int) $attachment_id, $atts['size'] );
}
add_shortcode( 'field_image', 'mysite_field_image' );

Use it with your own field name:

[field_image key="service_image" size="medium"]

When the field holds a valid ID, the image displays at medium size where the shortcode sits. The empty check means a blank field won’t break the page.

For a deeper look at reading custom fields, see how to use the WordPress get_post_meta function.

When the Field Stores an Image URL

Some fields save a URL instead of an ID. The function requires an ID, so convert the URL first with attachment_url_to_postid():

// Add to your child theme's functions.php
function mysite_field_image_url( $atts ) {
    $atts = shortcode_atts(
        array(
            'key'  => '',
            'size' => 'medium',
        ),
        $atts
    );
    if ( ! $atts['key'] ) {
        return '';
    }
    $image_url     = get_post_meta( get_the_ID(), $atts['key'], true );
    $attachment_id = attachment_url_to_postid( $image_url );
    if ( ! $attachment_id ) {
        return '';
    }
    return wp_get_attachment_image( $attachment_id, $atts['size'] );
}
add_shortcode( 'field_image_url', 'mysite_field_image_url' );

Use it the same way:

[field_image_url key="banner_image"]

When the conversion works, you get the same clean image tag as before. This only works when the URL points to a file in your Media Library. It won’t work for an image hosted elsewhere, since that file doesn’t have an attachment ID on your site.

Working with Advanced Custom Fields

Advanced Custom Fields (ACF) is popular for good reason, but its image field needs some care. Depending on the field’s return setting, it can return an attachment ID, a URL, or an array of image data.

This shortcode handles the ID and array cases, and it checks that ACF is active first:

// Add to your child theme's functions.php
function mysite_acf_image( $atts ) {
    $atts = shortcode_atts(
        array(
            'field' => '',
            'size'  => 'medium',
        ),
        $atts
    );
    if ( ! $atts['field'] || ! function_exists( 'get_field' ) ) {
        return '';
    }
    $image = get_field( $atts['field'] );
    if ( is_array( $image ) ) {
        $image = $image['ID'] ?? $image['id'] ?? 0;
    }
    if ( ! $image ) {
        return '';
    }
    return wp_get_attachment_image( (int) $image, $atts['size'] );
}
add_shortcode( 'acf_image', 'mysite_acf_image' );

Use it with your ACF field name:

[acf_image field="service_image"]

The function_exists()check stops the shortcode from causing an error if ACF is switched off. The is_array() check pulls the ID out when the field returns an array. Set the field to return the ID when you can, since it’s the simplest to work with here.

wp_get_attachment_image & get_post_meta Together

In core WordPress development, pairing get_post_meta with the wp_get_attachment_image function is standard practice. You fetch the attachment ID from the database with the first function, then pass it straight into the second function to handle the output:

// Fetch the attachment ID from post meta
$banner_id = get_post_meta( get_the_ID(), 'page_banner_id', true );

// Ensure we have an ID before printing
if ( $banner_id ) {
    echo wp_get_attachment_image( (int) $banner_id, 'full', false, array( 'class' => 'hero-banner' ) );
}

This keeps your template code light while ensuring your custom field images remain responsive, accessible, and fast.

wp_get_attachment_image Function & Advanced Custom Fields

If you use Advanced Custom Fields (ACF), you need to pay close attention to your field settings. ACF lets you set the Return Format of an Image field to one of three choices:

1. Image Array: Returns an array containing the image ID, URLs, alt text, and dimensions.
2. Image URL: Returns a plain string URL.
3. Image ID: Returns only the numeric attachment ID.

Always check your field settings in the ACF dashboard before writing your template code. Setting your ACF image fields to return the Image ID is the best choice, as it allows you to pass the value straight into wp_get_attachment_image():

// Assuming ACF Return Format is set to "Image ID"
$image_id = get_field( 'hero_image' );
if ( $image_id ) {
    echo wp_get_attachment_image( $image_id, 'large' );
}

If your field returns an array instead, you can extract the ID using $image[‘id’] before passing it to the function.

wp_get_attachment_image vs wp_get_attachment_image_src

WordPress offers a few ways to pull media files, and it’s easy to mix up the functions of wp_get_attachment_image and wp_get_attachment_image_src. They sound nearly identical, but they do completely different jobs.

wp_get_attachment_image

This function returns a complete, ready-to-use HTML <img> tag.

It includes the following attribues automatically:

• src
• srcset
• sizes
• alt
• width
• height
• loading.

Use this whenever you wish to print an image directly onto the page. 

wp_get_attachment_image_src

This function does not return HTML. Instead, it returns a plain array containing raw data about the image file:

• [0]: File URL.
• [1]: Image width (in pixels).
• [2]: Image height (in pixels).
• [3]: Boolean (true if it’s a resized version, false if original).

This is useful when you need the file URL on its own; for instance, when setting a CSS background image or building custom markup that requires distinct data points.

Which One Should Developers Use?

As a developer, you should use the wp_get_attachment_image function by default. It handles layout stability, responsive markup, and accessibility settings for you without extra effort. Only reach forwp_get_attachment_image_src() when you have a specific reason to construct your markup or CSS manually.

Keep Image Output Safe

The function handles safe output for the standard tag, so you don’t need to escape anything when you use it directly. The moment you build markup by hand, that safety is yours to add.

Escape:

• URLs with esc_url().
• Attribute values with esc_attr().
• Any text you print with esc_html().

Never send a raw value from a user or an unknown source directly to the page. Also, keep alt text clean and descriptive, not a dumping ground for whatever text you have to hand. These habits are small, and they save you real trouble later.

Performance Considerations for Image-Heavy Pages

Images are usually the heaviest thing on a page. There are a few choices that keep them from slowing you down:

• Match Image Size to Display Slot: Avoid loading a 2000-pixel image in a 200-pixel slot. Serve appropriate, registered sizes rather than full-size files to save bandwidth and improve load times.
• Compress Images: Reduce file sizes before or during upload. Proper compression maintains visual quality while significantly reducing file weight.
• Optimise Image Loops: Avoid rendering large images inside loops (e.g., printing 50 full-size images in a gallery). Use smaller image sizes within loops and rely on responsive markup to handle display scaling.
• Design for High-Latency & Mobile-Data Environments: Optimised images are vital in regions like South Africa, where users frequently rely on variable mobile data. During power outages (load-shedding), visitors depend heavily on mobile networks and battery power, making fast-loading, lightweight pages essential.
• Limit Overall Image Quantity: Even with optimised sizes and compression, loading too many images on a single page will degrade performance.

Accessibility, SEO, & Layout Stability

A clean image tag isn’t only about looks. A few attributes shape how usable and findable your images are. The function sets most of them, but the quality of some is your responsibility.

alt text is the big one. It describes the image for people using screen readers, and it provides search engines with context. Write what the image displays. For example, “Team standing outside the Cape Town office”.

Consider that stuffing keywords in place of a real description helps nobody, and it can harm you. If an image is purely decorative, give it an empty alt so screen readers skip it.

Width and height matter more than they seem. When the browser knows an image’s size before it loads, it reserves the correct space on the page. That stops content from jumping around as images come in. Less jumping means a calmer read, which counts for a lot on phones. The function includes these dimensions for you.

Loading and decoding assist with speed. WordPress adds loading and decoding settings on its own, so images lower down the page wait until they’re required. That saves data and shortens the first paint. You can override these in the attributes array, but the defaults suit most pages.

Class names connect your images to your CSS. Add your own class through the attributes array, then style it in your stylesheet. This keeps your design rules in one place instead of scattered inline.

Common Mistakes to Avoid

A few errors keep coming up. Watch for these:

• Using a post ID where an attachment ID is required. They are different numbers.
• Hardcoding image URLs when the file lives in your Media Library.
• Defaulting to full-size images when a smaller registered size would do.
• Forgetting to check what format a custom field returns.
• Assuming every uploaded image is attached to a post.
• Leaving alt text empty on images that carry meaning.
• Building manual markup without escaping the values.
• Echoing inside a shortcode instead of returning, which prints the image at the top of the page.
• Running big image loops without thinking about performance.
• Editing parent theme files directly, which wipes your changes on the next update. Use a child theme.
• Shipping without testing how images display on a phone.

Most of these are quick to avoid once you know they exist. A short review before you publish catches nearly all of them.

Troubleshooting

When an image won’t display, work through the likely causes in order. Start with the ID. Confirm it’s a real attachment ID, and not a post ID by mistake. Next, check that the image still exists in the Media Library, since a deleted file leaves a dead reference.

If the image is from a custom field, print the field value and see what’s stored. An empty field or an unexpected format is a common culprit. Also, check the template context. The function needs the correct post in scope to pull the correct image. Testing with a known, hardcoded ID is a quick way to tell whether the problem is the function or the data feeding it. A shortcode has its own tell. If its image lands at the top of the page instead of where you placed it, you’re echoing when you should return the output.

If the tag still won’t appear, dig into the logs. In this case, turning on WordPress Debug Mode on a staging copy surfaces PHP errors that are otherwise hidden.

You may also refer to how to configure WordPress error logs, which helps you capture the details. Clear any cache before you retest, since an old page can hide a fix you’ve already made.

Finally, check whether an image optimisation plugin is rewriting your tags, as that can change the output you expect.

South African Business & Agency Use Cases

The function earns its keep on everyday South African sites. Agencies use it to build reusable templates they can drop onto client after client, with image handling that just works. Developers use it for custom service pages, where each service pulls its own image from a field.

eCommerce stores lean on it for product and category images, served at the correct size so pages stay fast on mobile. Event sites use it for venue and speaker photos.

Training providers show course images the same way. Local businesses use them for team, branch, and project galleries, from a plumber in Pretoria to a law firm in Sandton. Publishers use it to place post images inside custom layouts without any fuss.

The thread through all of these is the same. Each requires clean, dynamic image output that scales with the content and holds up on the phones most visitors use. If you’re running sites of this type, dependable WordPress hosting in South Africa gives that image-heavy work a stable foundation.

Hosting & Development Environment

Image-heavy sites ask more of their hosting:

• Fast, reliable servers to keep large media loading smoothly.
• Current PHP versions to keep the function and its relatives running as they should.
• A staging site that allows you to test image changes safely before they go live.

Good backups also matter, so you can roll back if a change goes wrong. Error logs help you spot trouble early. Caching speeds up repeat visits, and image optimisation trims file sizes on the way out.

For heavier WordPress development work, direct access over SFTP or SSH makes template and plugin changes far easier.

Load-shedding is part of the picture here. Hosting with solid uptime keeps your site responding even when local power is patchy. If you’re building something media-heavy, VPS hosting for WordPress developers provides the room and control that busy image sites usually need.

POPIA & Image Metadata

Images can carry more than they show. A photo file can hold metadata, including the date, camera, and sometimes the location where it was taken. Staff photos, customer project shots, and event pictures can all contain personal details. Under POPIA, that type of personal information requires care.

Consider a few items. Receive permission before you publish photos of people. Be careful with location data in images of homes or private sites.

Also, remember that private files can leak beyond the page itself. Backups, logs, and custom metadata fields can all hold copies. Check what you expose through media fields and clear out what doesn’t need to be public. This is practical housekeeping, not legal advice, but it saves awkward problems later.

When to Ask a Developer to Help

Some image problems are worth handing over to a developer. Consult one when image output breaks a template, and you can’t see the reason. The same goes for custom fields that return arrays or values you don’t recognise, or when ACF or another field plugin is in the mix.

WooCommerce image output has its own quirks and often requires experienced hands. Request assistance when responsive sizes won’t work, when images shift your layout, or when performance is poor on image-heavy pages.

And if your debug log is filling with PHP errors, don’t guess your way through them. When you’re stuck, Domains.co.za support can point you in the right direction.

Final Thoughts

WordPress already has a smart way to put Media Library images on the page, and the wp_get_attachment_image function is it. Instead of hardcoding URLs, you hand WordPress an attachment ID and it returns clean, responsive, accessible markup. It supports templates, plugins, custom fields, and dynamic layouts, keeping your output in step with your media.

The habits that make it work are simple. Use the correct attachment ID, choose a sensible size, add clear alt text, and test on a phone before you ship. If those are correct, your images will look sharp, load fast, and behave on every screen.

From here, try the shortcodes on real content and adjust the sizes to fit your layouts. If you’re still getting your theme in place, how to install a WordPress theme is a good next step.

And if you want a steady home for an image-rich site, our support team can help you find the correct WordPress hosting. Build with confidence and let WordPress handle the heavy lifting on your images.

Power Up Your Site: How to Install a WordPress Plugin

VIDEO: Power Up Your Site: How to Install a WordPress Plugin

FAQS

Other Blogs of Interest

• WordPress Debug Mode Turns Hidden Website Errors Into Useful Diagnostic Evidence
• WordPress Version Control Helps Teams Build, Test, & Recover With Less Risk
• Your WordPress Header Does More Than Sit At The Top Of The Page
• Deleting Unused WordPress Themes Keeps Your Website Cleaner, Safer, And Easier To Manage
• The WordPress get_post_meta Function Helps You Turn Custom Fields Into Dynamic Content