amp-render

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

Usage

The amp-render component fetches JSON data, then renders that data using a template. amp-render can use data from a CORS JSON endpoint, from an amp-state state variable, or from amp-script.

Since amp-render's data can come from amp-script, you can use your own JavaScript to filter data, cap its size, create list functionality, and otherwise customize the component's behavior and appearance. If you prefer to use HTML attributes, amp-list provides a richer feature set.

You can specify a template in one of two ways:

• a template attribute that references an ID of an existing templating element.

<template id="my-template" type="amp-mustache">
  Your personal offer: ${{price}}</template>
<amp-render template="my-template" src="https://example.com/data.json">
</amp-render>

• a templating element nested directly inside the amp-render element.

<amp-render src="https://example.com/data.json">
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

For more details on templates, see AMP HTML Templates.

XHR batching

AMP batches XMLHttpRequests (XHRs) to JSON endpoints. This lets you use a single JSON request as a data source for multiple elements on an AMP page. For example, if your <amp-render> 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.

Placeholder and fallback

<amp-render> supports an optional placeholder and/or fallback.

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

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

<amp-render src="https://example.com/data.json">
  <div placeholder>Loading ...</div>
  <div fallback>Failed to load data.</div>
</amp-render>

Refreshing data

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

<button on="tap:my-component.refresh">Refresh</button>
<amp-render id="my-component" src="https://example.com/data.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-render>

Dynamic resizing

In some cases, we may need the <amp-render> element to resize on user interaction. For example, when the content does not fit within specified height attribute with layout="fixed-height" or the specified height is too large creating empty whitespace. The <amp-render element exposes a resizeToContents action that adjusts the height to fit the content. See the following example:

<button on="tap:my-component.resizeToContents()">Expand</button>
<amp-render
  id="my-component"
  src="https://example.com/data.json"
  layout="fixed-height"
  height="30">
    <template type="amp-mustache">
{{#cars}}        <p>{{make}} {{model}}</p>
{{/cars}}    </template>
</amp-render>

Substitutions

<amp-render> allows all standard URL variable substitutions. See the Substitutions Guide for more info.

For example:

<amp-render src="https://example.com/data.json?RANDOM"></amp-render>

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

Attributes

src (required)

The URL of the remote endpoint that returns the JSON that will be rendered within this <amp-render>. There are three valid protocols for the src attribute.

1. https: This must refer to a CORS HTTP service. Insecure HTTP is not supported.
2. amp-state: For initializing from <amp-state> data. See Initialization from <amp-state> section from amp-list for more details.
3. amp-script: For using <amp-script> functions as the data source. See Using <amp-script> as a data source section from amp-list for more details.

The src attribute may be omitted if the [src] attribute exists. [src] supports URL and non-URL expression values.

template

References an ID of a defined templating element. This attribute is not necessary if the template is a child of the amp-render element.

credentials

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.

The example below uses the "include" value in credentials to display personalized content:

<amp-render
  credentials="include"
  src="<%host%>/json/product.json?clientId=CLIENT_ID(myCookieId)"
>
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

xssi-prefix

Causes <amp-render> to strip a prefix from the fetched JSON before parsing. This can be useful for APIs that include security prefixes like )]} to help prevent cross site scripting attacks.

For example, let's say we had an API that returned this response:

)]}{ "items": ["value"] }

We could instruct amp-render to remove the security prefix like so:

<amp-render xssi-prefix=")]}" src="https://example.com/data.json"></amp-render>

key

Defines the expression to locate the sub-object to be rendered within the response. For example, let's say we had an API that returned this response:

{
  "automobiles": {
    "cars": {
      "german": {
        "make": "BMW",
        "model": "M3"
      },
      "american": {
        "make": "Tesla",
        "model": "Model X"
      }
    }
  }
}

If we just want to display the German cars from the response, we can use the key attribute.

<amp-render src="https://example.com/data.json" key="automobiles.cars.german">
  <template type="amp-mustache">
{{make}} {{model}}  </template>
</amp-render>

binding

Controls whether to block render to evaluate bindings (e.g. [text]) in children on pages using amp-render and amp-bind together.

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

Essentially, binding="always" is binding="refresh" that also blocks to evaluate bindings on the initial load of amp-render.

Common attributes

This element includes common attributes extended to AMP components.

Accessibility

For amp-render instances that do not have an aria-live attribute, aria-live="polite" will be added so any changes to the content are announced by screen readers. To override the addition of aria-live="polite", add aria-live="off".

Validation

See amp-render rules in the AMP validator specification.