wp_get_attachment_image() WordPress Function
The wp_get_attachment_image() function is used to retrieve the image for an attachment. The function can optionally resize the image and return it as an HTML img element, ready for display. This function is useful for displaying images attached to posts or pages, or for retrieving images for use in custom fields or elsewhere in your theme.
wp_get_attachment_image( int $attachment_id, string|int[] $size = 'thumbnail', bool $icon = false, string|array $attr = '' ) #
Get an HTML img element representing an image attachment.
Description
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.
Parameters
- $attachment_id
(int)(Required)Image attachment ID.
- $size
(string|int[])(Optional) Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order).
Default value: 'thumbnail'
- $icon
(bool)(Optional) Whether the image should be treated as an icon.
Default value: false
- $attr
(string|array)(Optional)Attributes for the image markup.
- 'src'
(string) Image attachment URL. - 'class'
(string) CSS class name or space-separated list of classes. Defaultattachment-$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. Defaults to 'lazy', depending on wp_lazy_loading_enabled().
Default value: ''
- 'src'
Return
(string) HTML img element or empty string on failure.
More Information
Usage
wp_get_attachment_image( $attachment_id, $size, $icon, $attr );
If the attachment is an image, the function returns an image at the specified size. For other attachments, the function returns a media icon if the $icon parameter is set to true.
To get attachment IDs dynamically in a template, you can use get_posts( array( 'post_type' => 'attachment' ) )
, etc.
Source
File: 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 ) ) ), ); // Add `loading` attribute. if ( wp_lazy_loading_enabled( 'img', 'wp_get_attachment_image' ) ) { $default_attr['loading'] = wp_get_loading_attr_default( 'wp_get_attachment_image' ); } $attr = wp_parse_args( $attr, $default_attr ); // 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 ( array_key_exists( 'loading', $attr ) && ! $attr['loading'] ) { unset( $attr['loading'] ); } // 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 .= ' />'; } /** * 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 ); }
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
5.5.0 | The $loading attribute was added. |
4.4.0 | The $srcset and $sizes attributes were added. |
2.5.0 | Introduced. |