AMP by Example
Playground

Introduction
Introduction

Components
Components

Advanced
Advanced

Samples & Templates
Samples & Templates

AMP Ads
AMP Ads

Edit in Playground View Demo

amp-bind

Edit on Github

Experimental Mode

This example uses the following experimental feature: [amp-bind]
Enable them below and learn more here.

Enable Dev Channel

Introduction

amp-bind allows you to add custom interactivity to your pages beyond using AMP's pre-built components.

It works by mutating elements in response to user actions via data binding and JS-like expressions.

For example, amp-bind can be used to:

  • Link two amp-carousel components into an image gallery with a scrolling thumbnail list.
  • Create an e-commerce product page where the UI changes if the user's currently selected item is not available.
Show Hidden Code Hide Code
<!doctype html>
<html ⚡>
<head>
  <meta charset="utf-8">
  <link rel="canonical" href="https://ampbyexample.com/components/amp-bind/">
  <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
  <script async src="https://cdn.ampproject.org/v0.js"></script>

Setup

Import the amp-bind component in the header.

  <script async custom-element="amp-bind" src="https://cdn.ampproject.org/v0/amp-bind-0.1.js"></script>
Show Hidden Code Hide Code
  <script async custom-element="amp-video" src="https://cdn.ampproject.org/v0/amp-video-0.1.js"></script>
  <style amp-boilerplate>body{-webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both;animation:-amp-start 8s steps(1,end) 0s 1 normal both}@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-moz-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}</style><noscript><style amp-boilerplate>body{-webkit-animation:none;-moz-animation:none;-ms-animation:none;animation:none}</style></noscript>
  <style amp-custom>
    .redBackground {
      background-color: red;
    }
    .greenBackground {
      background-color: green;
    }
  </style>
</head>
<body>

Configuring initial state

amp-bind works by binding elements to implicit JSON "state". This state can be initialized with one or more <amp-state> components.

  <amp-state id="allAnimals">
    <script type="application/json">
      {
        "dog": {
          "imageUrl": "/img/Border_Collie.jpg",
          "videoUrl": "/video/dog-video.mp4",
          "style": "greenBackground"
        },
        "cat": {
          "imageUrl": "/img/cat-looking-up-300x200.jpg",
          "videoUrl": "/video/cat-video.mp4",
          "style": "redBackground"
        }
      }
    </script>
  </amp-state>

Referencing implicit state in binding expressions is done by dot or bracket syntax, starting with the <amp-state> element's id, e.g. allAnimals.dog.imageUrl or allAnimals['cat']['imageUrl'].

  • The contents of <amp-state> must be a single JSON script.
  • Similar to the <amp-analytics> config, placing metadata at the end of the document helps the page display more quickly.

Creating data bindings

A data binding is a link between an HTML element and an expression. When the expression's value changes, the element is updated with that value.

Three types of element state can be bound:

  1. text for textContent
  2. class for CSS classes
  3. Element-specific attributes, for example, the src attribute for <amp-img> or <amp-video>.

To create a binding, create a new attribute on an element with the form:

[property]="expression"

Binding Text

The text of this <p> will change when the currentAnimal variable changes. currentAnimal is an uninitialized implicit state variable, which will be set when a state change is triggered (see below).

  <p [text]="'This is a ' + currentAnimal + '.'">This is a dog.</p>

This is a dog.

Binding Styles

Styling can be changed by applying css classes. It will override all the element's style classes. allAnimals is the id of the <amp-state> component above.


  <p [class]="allAnimals[currentAnimal].style" class="greenBackground">Each animal has a different background color.</p>

Each animal has a different background color.

Binding Attribute Values

Various AMP components support binding attribute values with amp-bind. For example, amp-img URLs can be changed.

  <amp-img src="/img/Border_Collie.jpg" width="300" height="200" [src]="allAnimals[currentAnimal].imageUrl">
  </amp-img>

The src URL for videos embedded with amp-video can be changed. At the moment, among all the AMP video components, only amp-video supports amp-bind.

  <amp-video src="/video/dog-video.mp4" [src]="allAnimals[currentAnimal].videoUrl" width="300" height="200" autoplay controls="true"></amp-video>

Triggering updates

Data bindings are re-evaluated when implicit state changes. Implicit state can be updated via the AMP.setState action.

  • AMP.setState merges new state into existing implicit state
  • Existing state can be overwritten, including state initialized by <amp-state> components
  <button class="button-primary" on="tap:AMP.setState(currentAnimal='cat')">Set to Cat</button>
</body>
</html>