amp-list.md

amp-list

Description	Fetches dynamic content from a CORS JSON endpoint and renders it using a supplied template.
Availability	Stable
Required Script	<script async custom-element="amp-list" src="https://cdn.ampproject.org/v0/amp-list-0.1.js"></script>
Examples	everything.amp.html

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

Validation Error	Description
The 'example1' tag is missing or incorrect, but required by 'example2'.	Error thrown when required amp-list extension .js script tag is missing or incorrect.
The mandatory attribute 'example1' is missing in tag 'example2'.	Error thrown when src attribute is missing.
Missing URL for attribute 'example1' in tag 'example2'.	Error thrown when src attribute is missing it's URL.
Malformed URL 'example3' for attribute 'example1' in tag 'example2'.	Error thrown when src attribute's URL is invalid.
Invalid URL protocol 'example3:' for attribute 'example1' in tag 'example2'.	Error thrown src attribute's URL is http; https protocol required.
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.

Usage

The amp-list defines data source using the following attributes:

• src defines a CORS URL. The URL's protocol must be HTTPS.
• credentials defines a credentials option as specified by the Fetch API. To send credentials, pass the value of "include". If this is set, the response must follow the AMP CORS security guidelines.

The response must be a JSON object that contains an array property "items":

{
  "items": []
}

The template can be specified using either of the following two ways:

• template attribute that references an ID of an existing template element.
• template element nested directly inside of this amp-list element.

For more details on templates see AMP HTML Templates.

Optionally, amp-list element can contain an element with overflow attribute. This element will be shown if AMP Runtime cannot resize the amp-list element as requested.

An example:

<amp-list src="https://data.com/articles.json?ref=CANONICAL_URL"
    width=300 height=200 layout=responsive>
  <template type="amp-mustache">
    <div>
      <amp-img src="{{imageUrl}}" width=50 height=50></amp-img>
      {{title}}
    </div>
  </template>
  <div overflow role=button aria-label="Show more" class="list-overflow">
    Show more
  </div>
</amp-list>

.list-overflow {
  position: absolute;
  bottom: 0;
}

The amp-list supports the following layouts: fixed, fixed-height, responsive, fill. See AMP HTML Layout System for details.

Substitutions

The amp-list allows all standard URL variable substitutions. See Substitutions Guide for more info.

For instance:

<amp-list src="https://foo.com/list.json?RANDOM"></amp-list>

may make a request to something like https://foo.com/list.json?0.8390278471201 where the RANDOM value is randomly generated upon each impression.

Behavior

The loading is triggered using normal AMP rules depending on how far the element is from the current viewport.

If amp-list needs more space after loading it requests the AMP runtime to update its height using the normal AMP flow. If AMP Runtime cannot satisfy the request for new height, it will display overflow element when available. Notice however, the typical placement of amp-list elements at the bottom of the document almost always guarantees that AMP Runtime can resize it.

By default, amp-list adds list ARIA role to the list element and listitem role to item elements rendered via the template.