AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-render

Description

Renders remote or inline data using a template.

 

Required Scripts

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

Your endpoint must implement the requirements specified in the CORS Requests in AMP spec.

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>

For <amp-render> instances with layout="responsive", resizeToContents action may break the aspect ratio since the height will change but width may remain fixed.

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.

Your endpoint must implement the requirements specified in the CORS Requests in AMP spec.

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>

Note that the key attribute is valid only when src is a URL. To access a sub-object in data fetched via JavaScript, use your own code to locate that sub-object before passing it to <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.

If binding attribute is not provided, default is refresh. This is a departure from amp-list binding where the default is always. Due to this change, if specifying only a bound src attribute ([src]), it is imperative to include the binding="always" attribute on the component to be able to display templated content on the initial load.

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.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub