AMP

amp-script

amp-script

Allows rendering of custom UI components running on third-party JavaScript.

AvailabilityOrigin Trial
This component is available under Origin Trial. To sign up for an Origin Trial please sign up at bit.ly/amp-script-trial.
Required Script
<script async custom-element="amp-script" src="https://cdn.ampproject.org/v0/amp-script-0.1.js"></script>

Overview

The amp-script component allows you to render widgets and other UI using custom third-party JavaScript, e.g. a React component.

amp-script is in active development and under experimental availability. It's subject to breaking API changes and should not yet be used in production.

A simple example

<!-- hello-world.html -->
<amp-script layout="container" src="https://example.com/hello-world.js">
  <button id="hello">Insert Hello World!</button>
</amp-script>
// hello-world.js
const button = document.getElementById('hello');
button.addEventListener('click', () => {
  const el = document.createElement('h1');
  el.textContent = 'Hello World!';
  // `document.body` is effectively the <amp-script> element.
  document.body.appendChild(el);
});

Enable the experiment via AMP.toggleExperiment('amp-script') in dev console.

For additional code samples, see examples/amp-script/.

How does it work?

amp-script is an AMP component wrapper for worker-dom.

worker-dom runs third-party JavaScript in a web worker containing a virtual DOM. The virtual DOM listens for mutations and forwards them to the main page which reflects the changes on the real DOM.

For design details, see the "Intent to Implement" issue. For more information on worker-dom, see the @ampproject/worker-dom repository.

Mutations and user actions

amp-script generally requires a user action to perform mutates to avoid unexpected UI jumps without user's input, but there are some exception to this rule.

Overall mutation rules are:

  1. Mutations are always accepted after a user action for a user action interval of 5 seconds.
  2. The 5 seconds interval is extended if the user script performs a fetch() operation.
  3. Smaller amp-script elements with height under 300px and non-container layout are allowed unlimitted mutations.

Interested in using <amp-script>?

We recommend developing against a local build of amp-script. This enables dev-only debugging hooks e.g. human-readable postMessage events.

See our Quick Start guide for setting up your local environment.

FAQ

  1. Which JavaScript APIs can I use?

  2. Currently, most DOM elements and their properties are supported. DOM query APIs like querySelector have partial support. Browser APIs like History are not implemented yet. We'll publish an API support matrix soon.

  3. Can you support ____ API?

    • Our feature timelines are informed by your real-world use cases! Please file an issue and mention @choumx and @kristoferbaxter.
ご不明な点がある場合

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