Description Fetches content dynamically from a CORS JSON endpoint and renders it using a supplied template.
Required Script <script async custom-element="amp-list" src=""></script>
Supported Layouts fill, fixed, fixed-height, flex-item, nodisplay, responsive
Examples See AMP By Example's amp-list example.


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 template element.
  • a template element nested directly inside the amp-list element.

For more details on templates, see AMP HTML Templates.

Example: 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.

Show full code

Here is the JSON file that we used:

 "items": [
     "title": "AMP YouTube Channel",
     "url": ""
     "title": "",
     "url": ""
     "title": "AMP By Example",
     "url": ""
     "title": "AMP Start",
     "url": ""

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.

By default, amp-list adds a list ARIA role to the list element and a listitem role to item elements rendered via the 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 element can contain an element with an overflow attribute. This element is shown if the AMP Runtime cannot resize the amp-list element as requested.

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 Runtime displays the overflow element.

Show full code

Here's the CSS for the overflow:

.list-overflow[overflow] {
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;

Placeholder and fallback

Optionally, amp-list supports a placeholder and/or fallback.

  • A placeholder is a child element with the placeholder attribute. This element is shown until the amp-list loads successfully. If a fallback is also provided, the placeholder is hidden when the amp-list fails to load.
  • A fallback is a child element with the fallback attribute. This element is shown if the amp-list fails to load.

Learn more in Placeholders & Fallbacks. Note that a child element cannot be both a placeholder and a fallback.

<amp-list src="">
  <div placeholder>Loading ...</div>
  <div fallback>Failed to load data.</div>

Refreshing data

The amp-list element exposes a refresh action that other elements can reference in on="tap:..." attributes.

<button on="tap:myList.refresh">Refresh List</button>
<amp-list id="myList" src="">
  <template type="amp-mustache">

Dynamic Resizing

Experimental: amp-list-resizable-children

In several cases, we may need the amp-list to resize on user interaction. For example, when the amp-list contains an amp-accordion that a user may tap on, when the contents of the amp-list change size due to bound CSS classes, or when the number of items inside an amp-list changes due to a bound [src] attribute. The changeToLayoutContainer action handles this by changing the amp list to layout="CONTAINER" when triggering this action. See the following example:

  <button on="list.changeToLayoutContainer()">Show Grid</button>
  <amp-list id="list"
    width="396" height="80" layout="responsive"
    <template type="amp-mustache">

This action is experimentally available under amp-list-resizable-children.


src (required)

The URL of the remote endpoint that returns the JSON that will be rendered within this amp-list. This must be a CORS HTTP service. The URL's protocol must be HTTPS.

The src attribute may be omitted if the [src] attribute exists. This is useful when rendering content as a result of a user gesture instead of on page load when working with amp-bind.

credentials (optional)

Defines a credentials option as specified by the Fetch API.

  • Supported values: omit, include
  • Default: omit

To send credentials, pass the value of include. If this value is set, the response must follow the AMP CORS security guidelines.

Here's an example that specifies including credentials to display personalized content in a list:

<amp-list credentials="include"
  <template type="amp-mustache">
    Your personal offer: ${{price}}
items (optional)

Defines the expression to locate the array to be rendered within the response. This is a dot-notated expression that navigates via fields of the JSON response. By defaut amp-list expects an array, the single-item attribute may be used to load data from an object.

  • The default value is "items". The expected response: {items: [...]}.
  • If the response itself is the desired array, use the value of ".". The expected response is: [...].
  • Nested navigation is permitted (e.g., "field1.field2"). The expected response is: {field1: {field2: [...]}}.

When items="items" is specified (which, is the default) the response must be a JSON object that contains an array property called "items":

  "items": [...]

max-items (optional)

An integer value specifying the maximum length of the items array to be rendered. The items array will be truncated to max-items entries if the returned value exceeds max-items.

single-item (optional)

Causes amp-list to treat the returned result as if it were a single element array. An object response will be wrapped in an array so {items: {...}} will behave as if it were {items: [{...}]}.

reset-on-refresh (optional)

Displays a loading indicator and placeholder again when the list's source is refreshed via amp-bind or the refresh() action.

By default, this will only trigger on refreshes that cause a network fetch. To reset on all refreshes, use reset-on-refresh="always".

[is-layout-container] (experimental, optional)

This is a bindable attribute that should always be false by default. When set to true via bind, it changes the layout of the amp-list to layout CONTAINER. This attribute is useful for handling dynamic resizing for amp-list. This attribute cannot be true by default for the same reason why <amp-list> does not support layout CONTAINER--it potentially causes content jumping on first load. This attribute is experimentally available under amp-list-resizable-children. Alternatively, one may also use the changeToLayoutContainer action.

binding (optional)

For pages using amp-list that also use amp-bind, controls whether or not to block render on the evaluation of bindings (e.g. [text]) in rendered children.

We recommend using binding="no" or binding="refresh" for faster performance.

  • binding="no": Never block render (fastest).
  • binding="refresh": Don't block render on initial load (faster).
  • binding="always": Always block render (slow).

If binding attribute is not provided, default is always.

common attributes

This element includes common attributes extended to AMP components.


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

For example:

<amp-list src=""></amp-list>

may make a request to something like where the RANDOM value is randomly generated upon each impression.


See amp-list rules in the AMP validator specification.