| Description | A runtime-managed replacement for the HTML img tag. |
| Supported Layouts | fill, fixed, fixed-height, flex-item, intrinsic, nodisplay, responsive |
| Examples | See AMP By Example's amp-img example. |
[TOC]
The runtime may choose to delay or prioritize resource loading based on the viewport position, system resources, connection bandwidth, or other factors. The amp-img components allows the runtime to effectively manage image resources this way.
amp-img components, like all externally fetched AMP resources, must be given an
explicit size (as in width / height) in advance, so that the aspect ratio can be known without fetching the image. Actual layout behavior is determined by the layout attribute.
{% call callout('Read on', type='read') %} Learn more about layouts in the AMP HTML Layout System spec and Supported Layouts. {% endcall %}
In the following example, we display an image that responds to the size of the viewport by setting layout=responsive. The image stretches and shrinks according to the aspect ratio specified by the width and height.
{% call callout('Read on', type='read') %} Learn about responsive AMP pages in the Create Responsive AMP Pages guide. {% endcall %}
If the resource requested by the amp-img component fails to load, the space will be blank unless a fallback child is provided. A fallback is only executed on the initial layout and subsequent src changes after the fact (through resize + srcset for example) will not have a fallback for performance implications.
In the following example, if the browser doesn't support WebP, the fallback JPG image displays:
A placeholder background color or other visual can be set using CSS selector and style on the element itself.
Additional image features like captions can be implemented with standard HTML (for example, figure and figcaption).
{% call callout('Read on', type='read') %}
Learn more about using amp-img from these resources:
- Placeholders & fallbacks
- Include Images & Video {% endcall %}
src
This attribute is similar to the src attribute on the img tag. The value must be a URL that points to a publicly-cacheable image file. Cache providers may rewrite these URLs when ingesting AMP files to point to a cached version of the image.
srcset
Same as srcset attribute on the img tag. The behavior will be polyfilled where not natively supported.
sizes
Same as sizes attribute on the img tag.
{% call callout('Read on', type='read') %}
See Responsive images with srcset, sizes & heights for usage of sizes and srcset.
{% endcall %}
alt
A string of alternate text, similar to the alt attribute on img.
attribution
A string that indicates the attribution of the image. For example, attribution="CC courtesy of Cats on Flicker"
height and width
An explicit size of the image, which is used by the AMP runtime to determine the aspect ratio without fetching the image.
common attributes
This element includes common attributes extended to AMP components.
amp-img can be styled directly via CSS properties. Setting a grey background
placeholder for example could be achieved via:
amp-img {
background-color: grey;
}If you want your image to scale as the window is resized but up to a maximum width (so the image doesn't stretch beyond its width):
- Set
layout=responsivefor<amp-img>. - On the container of the image, specify the
max-width:<max width to display image>CSS attribute. Why on the container? Anamp-imgelement withlayout=responsiveis a block-level element, whereas,<img>is inline. Alternatively, you could setdisplay: inline-blockin your CSS for the amp-img element.
Both the responsive and intrinsic layouts create an image that will scale automatically. The main difference is that the intrinsic layout uses an SVG image as it's scaling element. This will make it behave in the same way as a standard html image while retaining the benifit of the browser knowing the image size on initial layout. The intrinsic layout will have an intrinsic size and will inflate a floated div until it reaches either the natural image size or a CSS constraint like max-width. The responsive layout will render 0x0 in a floated div becasue it takes its size from the parent which in a float has no natural size.
If you want your image to display at a fixed size:
- Set
layout=fixedfor<amp-img>. - Specify the
widthandheight.
{% call callout('Read on', type='read') %}
Learn about the inferred layout if you don't specify the layout attribute.
{% endcall %}
For responsive images, the width and height do not need to match the exact width and height of the amp-img; those values just need to result in the same aspect-ratio.
For example, instead of specifying width="900" and height="675", you can just specify width="1.33" and height="1".
The srcset attribute should be used to provide different resolutions of the same image, that all have the same aspect ratio. The AMP runtime will automatically choose the most appropriate file from srcset based on the screen resolution and width of the user's device.
In contrast, the media attribute shows or hides AMP components, and should be used when designing responsive layouts. The appropriate way to display images with differing aspect ratios is to use multiple <amp-img> components, each with a media attribute that matches the screen widths in which to show each instance.
See the guide on creating responsive AMP pages for more details.
The AMP layout system requires the aspect ratio of an image in advance before fetching the image; however, in some cases you might not know the image's dimensions. To display images with unknown dimensions and maintain the aspect ratios, combine AMP's fill layout with the object-fit CSS property. For more information, see AMP By Example's How to support images with unknown dimensions.
See amp-img rules in the AMP validator specification.