Skip to content

Latest commit

 

History

History
117 lines (91 loc) · 6.09 KB

amp-img.md

File metadata and controls

117 lines (91 loc) · 6.09 KB
Raw

amp-img

Description A runtime-managed replacement for the HTML img tag.
Availability Stable
Examples amp-img.html
responsive.amp.html

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.

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.

A placeholder background color or other visual can be set using CSS selector and style on the element itself.

The amp-img includes attributes for denoting attribution via the attribution attribute.

Additional image features like captions can be implemented with standard HTML - using the figure and figcaption elements, for example.

Attributes

src

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.

alt

A string of alternate text, similar to the alt attribute on img.

attribution

A string that indicates the attribution of the image. E.g. attribution="CC courtesy of Cats on Flicker"

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

Validation errors

The following lists validation errors specific to the amp-img tag (see also amp-img in the AMP validator specification):

Validation Error Description
The tag 'example1' may only appear as a descendant of tag 'example2'. Did you mean 'example3'? Error thrown if your AMP document uses img instead of amp-img. Error message: The tag img may only appear as a descendant of tag noscript. Did you mean amp-img?.
The tag 'example1' is missing a mandatory attribute - pick one of example2. Error thrown when neither src or srcset is included. One of these attributes is mandatory.
Missing URL for attribute 'example1' in tag 'example2'. Error thrown when src or srcset attribute is missing its URL.
Malformed URL 'example3' for attribute 'example1' in tag 'example2'. Error thrown when src or srcset attribute's URL is invalid.
The implied layout 'example1' is not supported by tag 'example2'. Error thrown when implied layout is set to CONTAINER; this layout type isn't supported.
The specified layout 'example1' is not supported by tag 'example2'. Error thrown when specified layout is set to CONTAINER; this layout type isn't supported.
The property 'example1' in attribute 'example2' in tag 'example3' is set to 'example4', which is invalid. Error thrown when invalid value is given for attributes height or width. For example, height=auto triggers this error for all supported layout types, with the exception of NODISPLAY.