amp-list

1.0 0.1

<script async custom-element="amp-list" src="https://cdn.ampproject.org/v0/amp-list-0.1.js"></script>

Usage

The amp-list component fetches dynamic content from a CORS JSON endpoint. The response from the endpoint contains data, which is rendered in the specified template.

You can specify a template in one of two ways:

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

For more details on templates, see AMP HTML Templates.

Displaying a dynamic list

In the following example, we retrieve JSON data that contains URLs and titles, and render the content in a nested amp-mustache template.

<amp-list
  width="auto"
  height="100"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-urls.json"
>
  <template type="amp-mustache">

    <div class="url-entry">
      <a href="{{url}}">{{title}}</a>
    </div>
  </template>
</amp-list>

Here is the JSON file that we used:

{
  "items": [
    {
      "title": "AMP YouTube Channel",
      "url": "https://www.youtube.com/channel/UCXPBsjgKKG2HqsKBhWA4uQw"
    },
    {
      "title": "AMPproject.org",
      "url": "https://www.ampproject.org/"
    },
    {
      "title": "AMP",
      "url": "https://amp.dev/"
    },
    {
      "title": "AMP Start",
      "url": "https://ampstart.com/"
    }
  ]
}

Here is how we styled the content fetched:

amp-list div[role='list'] {
  display: grid;
  grid-gap: 0.5em;
}

The request is always made from the client, even if the document was served from the AMP Cache. 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 the AMP runtime cannot satisfy the request for the new height, it will display the overflow element when available. Notice however, that the typical placement of <amp-list> elements at the bottom of the document almost always guarantees that the AMP runtime can resize them.

Accessibility considerations for amp-list

By default, <amp-list> adds a list ARIA role to the list element and a listitem role to item elements rendered via the template. If the list element or any of its children are not "tabbable" (accessible by keyboard keys such as the a and button elements or any elements with a positive tabindex), a tabindex of 0 will be added by default to the list item. This behaviour is arguably not always appropriate - generally, only interactive controls/content should be focusable. If you want to suppress this behaviour, make sure to include tabindex="-1" as part of the outermost element of your template.

<template type="amp-mustache">

  <div class="item">{{item}}</div>
  <div class="price">{{price}}</div>
</template>

<template type="amp-mustache">

  <div>
    <div class="item">{{item}}</div>
    <div class="price">{{price}}</div>
  </div>
</template>

XHR batching

AMP batches XMLHttpRequests (XHRs) to JSON endpoints, that is, you can use a single JSON data request as a data source for multiple consumers (e.g., multiple <amp-list> elements) on an AMP page. For example, if your <amp-list> makes an XHR to an endpoint, while the XHR is in flight, all subsequent XHRs to the same endpoint won't trigger and will instead return the results from the first XHR.

In <amp-list>, you can use the items attribute to render a subset of the JSON response, allowing you to have multiple <amp-list> elements rendering different content but sharing a single XHR.

Specifying an overflow

Optionally, the <amp-list> component can contain an element with the overflow attribute. AMP will display this element if all of the following conditions are met:

• The contents rendered into the amp-list exceed its specified size.
• The bottom of amp-list is within the viewport.
• The bottom of amp-list is not near the bottom of the page (defined as the minimum of either the bottom 15% of the document or the bottom 1000px)

If amp-list is outside the viewport, it will be automatically expanded.

Example: Displaying an overflow when the list needs more space

In the following example, we display a list of images and titles. Because the <amp-list> content requires more space than available, the AMP framework displays the overflow element.

<amp-list