wp_get_attachment_image() │ WP 2.5.0

Get an HTML img element representing an image attachment

While $size will accept an array, it is better to register a size with add_image_size() so that a cropped version is generated. It's much more efficient than having to find the closest-sized image and then having the browser scale down the image.

Uses: wp_get_attachment_image_src(), wp_calculate_image_srcset(), wp_calculate_image_sizes()
Used By: get_the_post_thumbnail(), get_custom_logo()
Hooks from the function

Return

String. HTML img element or empty string on failure.

Usage

wp_get_attachment_image( $attachment_id, $size, $icon, $attr );
$attachment_id(int) (required)
Image attachment ID.
$size(string|int[])
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order).
Default: 'thumbnail'
$icon(true|false)
Whether the image should be treated as an icon.
Default: false
$attr(string|array)

Attributes for the image markup.

Default: ''

  • src(string)
    Image attachment URL.

  • class(string)
    CSS class name or space-separated list of classes.
    Default: attachment-$size_class size-$size_class, where $size_class is the image size being requested

  • alt(string)
    Image description for the alt attribute.

  • srcset(string)
    The 'srcset' attribute value.

  • sizes(string)
    The 'sizes' attribute value.

  • loading(string|false)
    The 'loading' attribute value. Passing a value of false will result in the attribute being omitted for the image.
    Default: 'lazy', depending on wp_lazy_loading_enabled()

  • decoding(string)
    The 'decoding' attribute value. Possible values are 'async' (default), 'sync', or 'auto'. Passing false or an empty string will result in the attribute being omitted.

Examples

0

#1 Output a ready-to-use HTML image

Let's display the medium size image (<img> tag) of the attached file with ID 651:

<?php echo wp_get_attachment_image( 651, 'medium'); ?>

It outputs something like this HTML:

<img width="250" height="250" 
	 src="http://example.com/image-250x250.png" 
	 class="attachment-medium size-medium" 
	 alt="Text from Alt Text field"
/>

alt text will be filled in only if it is specified for the attachment in the special field (alt text). The alt does not include the text from the title, description or caption of the image.

0

#2 Example of a custom size

Display a picture of the specified size 20x20 pixels, for attachments of the "image" type, and the corresponding icon for other attachment types (the 3rd parameter):

<?php echo wp_get_attachment_image( $attach_id, [ 20,20 ], true); ?>

$attach_id - can be taken as get_post_thumbnail_id() or $post->ID if you use the loop of images. You can create such a loop by using function get_posts() (get_posts('post_type=attachment')).

0

#3 Specify class, alt and title attributes for the picture 

$params = [ 'class' => 'some-class', 'alt' => 'alt picture', 'title' => 'title picture' ]

$tag = wp_get_attachment_image( 15108, 'medium', false, $params );

We get it:

<img width="588" height="216"
 src="/wp-content/uploads/2021/12/clipboard-image-122190.png"
 class="attachment-medium size-medium"
 alt="alt pictures"
 loading="lazy"
 title="title picture"/>
0

#4 Show all images attached to the post

To display all of the images and titles attached to a certain page and display them as a list of bullets you can use the following:

<ul>
	<?php if ( have_posts() ) : while ( have_posts() ) : the_post();

		$attachments = get_posts( array(
			'post_type'   => 'attachment',
			'numberposts' => -1,
			'post_status' => null,
			'post_parent' => $post->ID
		) );

		if ( $attachments ) {
			foreach ( $attachments as $attachment ) {
				?>
				<li><?php echo wp_get_attachment_image( $attachment->ID, 'full' ); ?>
					<p><?php echo apply_filters( 'the_title', $attachment->post_title ); ?></p>
				</li>
				<?php
			}
		}
	endwhile; endif; ?>
</ul>

Changelog

Since 2.5.0 Introduced.
Since 4.4.0 The $srcset and $sizes attributes were added.
Since 5.5.0 The $loading attribute was added.
Since 6.1.0 The $decoding attribute was added.

wp_get_attachment_image() code WP 6.4.1

wp-includes/media.php 
function wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = false, $attr = '' ) {
	$html  = '';
	$image = wp_get_attachment_image_src( $attachment_id, $size, $icon );

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

		$attachment = get_post( $attachment_id );
		$hwstring   = image_hwstring( $width, $height );
		$size_class = $size;

		if ( is_array( $size_class ) ) {
			$size_class = implode( 'x', $size_class );
		}

		$default_attr = array(
			'src'   => $src,
			'class' => "attachment-$size_class size-$size_class",
			'alt'   => trim( strip_tags( get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ) ) ),
		);

		/**
		 * Filters the context in which wp_get_attachment_image() is used.
		 *
		 * @since 6.3.0
		 *
		 * @param string $context The context. Default 'wp_get_attachment_image'.
		 */
		$context = apply_filters( 'wp_get_attachment_image_context', 'wp_get_attachment_image' );
		$attr    = wp_parse_args( $attr, $default_attr );

		$loading_attr              = $attr;
		$loading_attr['width']     = $width;
		$loading_attr['height']    = $height;
		$loading_optimization_attr = wp_get_loading_optimization_attributes(
			'img',
			$loading_attr,
			$context
		);

		// Add loading optimization attributes if not available.
		$attr = array_merge( $attr, $loading_optimization_attr );

		// Omit the `decoding` attribute if the value is invalid according to the spec.
		if ( empty( $attr['decoding'] ) || ! in_array( $attr['decoding'], array( 'async', 'sync', 'auto' ), true ) ) {
			unset( $attr['decoding'] );
		}

		/*
		 * If the default value of `lazy` for the `loading` attribute is overridden
		 * to omit the attribute for this image, ensure it is not included.
		 */
		if ( isset( $attr['loading'] ) && ! $attr['loading'] ) {
			unset( $attr['loading'] );
		}

		// If the `fetchpriority` attribute is overridden and set to false or an empty string.
		if ( isset( $attr['fetchpriority'] ) && ! $attr['fetchpriority'] ) {
			unset( $attr['fetchpriority'] );
		}

		// Generate 'srcset' and 'sizes' if not already present.
		if ( empty( $attr['srcset'] ) ) {
			$image_meta = wp_get_attachment_metadata( $attachment_id );

			if ( is_array( $image_meta ) ) {
				$size_array = array( absint( $width ), absint( $height ) );
				$srcset     = wp_calculate_image_srcset( $size_array, $src, $image_meta, $attachment_id );
				$sizes      = wp_calculate_image_sizes( $size_array, $src, $image_meta, $attachment_id );

				if ( $srcset && ( $sizes || ! empty( $attr['sizes'] ) ) ) {
					$attr['srcset'] = $srcset;

					if ( empty( $attr['sizes'] ) ) {
						$attr['sizes'] = $sizes;
					}
				}
			}
		}

		/**
		 * Filters the list of attachment image attributes.
		 *
		 * @since 2.8.0
		 *
		 * @param string[]     $attr       Array of attribute values for the image markup, keyed by attribute name.
		 *                                 See wp_get_attachment_image().
		 * @param WP_Post      $attachment Image attachment post.
		 * @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).
		 */
		$attr = apply_filters( 'wp_get_attachment_image_attributes', $attr, $attachment, $size );

		$attr = array_map( 'esc_attr', $attr );
		$html = rtrim( "<img $hwstring" );

		foreach ( $attr as $name => $value ) {
			$html .= " $name=" . '"' . $value . '"';
		}

		$html .= ' />';
	}

	/**
	 * Filters the HTML img element representing an image attachment.
	 *
	 * @since 5.6.0
	 *
	 * @param string       $html          HTML img element or empty string on failure.
	 * @param int          $attachment_id Image attachment ID.
	 * @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 bool         $icon          Whether the image should be treated as an icon.
	 * @param string[]     $attr          Array of attribute values for the image markup, keyed by attribute name.
	 *                                    See wp_get_attachment_image().
	 */
	return apply_filters( 'wp_get_attachment_image', $html, $attachment_id, $size, $icon, $attr );
}

wp attachment image

Images

Post Thumbnails