Description A runtime-managed replacement for the HTML img tag.
Supported Layouts fill, fixed, fixed-height, flex-item, nodisplay, responsive
Examples See AMP By Example's amp-img example.

Behavior

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.

Example: Displaying a responsive image

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.

Show full code

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.

Example: Specifying a fallback image

In the following example, if the browser doesn't support WebP, the fallback JPG image displays:

Show full code

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).

Attributes

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.

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.

Styling

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;
}

Tips & Tricks

Scaling an image up to a maximum width

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):

  1. Set layout=responsive for <amp-img>.
  2. On the container of the image, specify the max-width:<max width to display image> CSS attribute. Why on the container? An amp-img element with layout=responsive is a block-level element, whereas, <img> is inline. Alternatively, you could set display: inline-block in your CSS for the amp-img element.

Setting a fixed sized image

If you want your image to display at a fixed size:

  1. Set layout=fixed for <amp-img>.
  2. Specify the width and height.

Setting the aspect ratio

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".

Show full code

Validation

See amp-img rules in the AMP validator specification.