How to Use the wp_get_attachment_image Function in WordPress + Useful Examples

The wp_get_attachment_image is a WordPress function that lets you easily retrieve and display image attachments based on their IDs.

Whether you’re building a custom theme or a plugin, this function provides a flexible way to display images with custom sizes and attributes.

In this tutorial, we’ll go over the wp_get_attachment_image() function and explain its parameters. We’ll also provide a few popular use cases you can test on your hosted WordPress website.

Download all in one WordPress cheat sheet

Parameters of the wp_get_attachment_image Function

The wp_get_attachment_image() function lets users retrieve an HTML img element for an image attachment.

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

By default, the wp_get_attachment_image() function requires at least one parameter, the attachment ID, which is the unique identifier for the image. The function then outputs the full-sized image without additional HTML attributes or customization.

Furthermore, you can add various additional parameters for customizing the image output, such as the image size, CSS class, or alt text:

$attachment_id

This is necessary to specify the attachment image ID that will be displayed. If the parameter is empty or set to false, the function won’t return any image.

$size

An optional parameter that defines the WordPress image size to display. You can specify any registered image size name, for example, thumbnail, medium, large, or a custom size in pixels.

$icon

Another optional parameter which determines whether the image should be treated as an icon. If set to true, the function will display the attachment icon instead of the actual image.

$attr

This parameter lets you add more attributes to the image tag, such as a class or a style. You can pass an array of key-value pairs to add the following attributes:

• class – handles the CSS class of the image tag. You can add multiple classes by creating a space-separated list.
• alt – sets the image’s alt text. An alt attribute value is important for accessibility and WordPress SEO purposes.
• srcset – specifies multiple image sources with different resolutions, sizes, or aspect ratios. The browser will automatically choose the best source based on the device’s screen resolution.
• sizes – works together with the srcset attribute. It specifies the image size displayed on a page based on the available space.
• loading – determines how the image loads. For example, the default value is lazy for lazy loading.
• decoding – lets you specify how the browser should interpret the image. Valid values are async to decode the image asynchronously, sync to decode the image synchronously, or auto.

How to Use wp_get_attachment_image

In this section, we’ll explain how to use the wp_get_attachment_image() function effectively. Check the commented code below for more information:

<?php
if ( has_post_thumbnail() ) { // check if the post has a featured image
    $thumbnail_id = get_post_thumbnail_id(); // get the ID of the post thumbnail image
    $image = wp_get_attachment_image( $thumbnail_id, 'large' ); // get the HTML code for the post default thumbnail image
    echo $image; // display the image
}
?>

Here is what we did:

1. Used the has_post_thumbnail() function to check if the post has a featured image.
2. Applied get_post_thumbnail_id() to get the ID of the featured image.
3. Used the wp_get_attachment_image() function to get the HTML code for the image.
4. Passed the $thumbnail_id variable as the ID of the image and large as the specified size.
5. Employed echo to output the image HTML code to the page.

Remember that you can replace the large parameter with any registered image size.

Examples of the wp_get_attachment_image WordPress Function

Check out a few popular use cases for the wp_get_attachment_image() function to understand how it can help you with your WordPress projects.

Outputting a Ready-To-Use HTML Image

The simplest way to test the wp_get_attachment_image() function is to pass an image attachment ID to it.

<?php echo wp_get_attachment_image( 37);?>

Remember that we didn’t provide any specific image size in this example. Hence, the function retrieved the full-sized image with attachment ID 37.

In HTML, the output will look like this. The alt text will exist if it is already added:

<img width="500" height="500" src="http://example.com/wp-content/uploads/2024/03/image.jpg" class="attachment-full size-full" alt="Alt Attribute">

By default, HTML sets the full-sized images to 500 pixels wide and 500 pixels in height. However, the actual width and height values in pixels may vary depending on their original dimensions.

Using a Custom Size

Custom-sized images can improve website performance by reducing page load times and enhancing the overall look. They also ensure consistency across different devices and screens:

<?php echo wp_get_attachment_image( 37, [ 100,100 ], true); ?>

In HTML, the output will look like this:

<img width="40" height="40" src="http://example.com/wp-content/uploads/2024/03/image.jpg" class="attachment-thumbnail size-thumbnail" alt="Description for the alt text">

In this case, the second parameter of the wp_get_attachment_image() function is an array containing the width and height in pixels of the requested image size. The third parameter is set to true, meaning the function will crop the image to the exact dimensions specified in the array.

Here’s how it looks on a live website:

Displaying All Images Associated With the Post

You can display all images associated with a specific post ID. Doing so lets you view all the relevant pictures without navigating through the whole post.

<?php
$attachments = get_attached_media('image', get_the_ID());
if (!empty($attachments)) {
    foreach ($attachments as $image) {
        echo wp_get_attachment_image($image->ID, 'full');
    }
} 
?>

In this example, the code retrieves all the attached images of the current post using the get_attached_media() function and loops through them using a foreach loop.

For each image, it calls the wp_get_attachment_image() function to retrieve the full-sized version of the image with the attachment ID.

Specifying Class, Alt, and Title Attributes of an Image

It’s also possible to specify custom class, alt text, and title attributes for an image. All you need to do is set them to a variable. In our case, its $custom:

<?php
$custom = [ 'class' => 'my-class', 'alt' => 'alt text', 'title' => 'my title' ];
echo wp_get_attachment_image( 37, 'medium', false, $custom );
?>

In this example, the fourth parameter is an array containing the additional attributes for the <img> tag.

Conclusion

wp_get_attachment_image() is a versatile WordPress function that enables you to easily display images attached to posts or pages.

In this tutorial, we’ve covered the wp_get_attachment_image() function and its parameters. We’ve also provided some use cases you can test on your WordPress website.

We hope that you found this tutorial useful. In case you have any questions, leave a comment below.