AMP Roadshow is coming to Atlanta & Berlin!
AMP
  • websites

amp-autocomplete

Experimental

This example uses the following experimental feature: amp-autocomplete. Enable the experiment via the button below. Some components require the AMP Dev Channel to be enabled as well. Learn more about experimental features.

Introduction

An autocomplete-enabled input field suggests completed results corresponding to the user input as they type into the input field.

This feature can help the user to carry out their task more quickly.

Data can either be fetched from a JSON endpoint or locally from amp-state.

Setup

Import the amp-autocomplete component.

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

Import the amp-form component.

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

Optional: amp-bind is needed for dynamically changing the data source of an amp-autocomplete.

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

Optional: amp-mustache is needed for rich-content templating and client-side rendering of form responses.

<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>

Basic usage

An amp-autocomplete must always be nested in a form and have an input field and a datasource.

When a user types into this input field, relevant suggestions will automatically appear below the input field.

A datasource must be a JSON object containing an array property items, and can be specified inline with a child script type="application/json" tag, or a server endpoint specified with a src attribute.

<form>
  <amp-autocomplete filter="substring"
    min-characters="0">
    <input type="text">
    <script type="application/json">
      {
        "items": ["apple", "orange", "banana"]
      }
    </script>
  </amp-autocomplete>
</form>

Alternatively, a datasource can also be provided as remote data through the src attribute.

<form>
  <amp-autocomplete filter="substring"
    min-characters="0"
    src="/static/samples/json/amp-autocomplete-cities.json">
    <input type="text">
  </amp-autocomplete>
</form>

Dynamic src

The content of an amp-autocomplete can be changed dynamically by modifying its src value using amp-bind.


<div>
  <div class="suggest-data">
    <button on="tap:AMP.setState({ srcUrl: '/static/samples/json/amp-autocomplete-countries.json' })">Suggest countries</button>
    <button on="tap:AMP.setState({ srcUrl: '/static/samples/json/amp-autocomplete-cities.json' })">Suggest US cities</button>
  </div>
  <form class="sample-form"
    method="post"
    action-xhr="https://ampbyexample.com/components/amp-form/submit-form-input-text-xhr"
    target="_top">
    <div class="input-field">
      <amp-autocomplete filter="substring"
        min-characters="0"
        src="/static/samples/json/amp-autocomplete-cities.json"
        [src]="srcUrl">
        <input type="text"
          name="name"
          required>
      </amp-autocomplete>
      <input name="submit-button"
        type="submit"
        value="Submit"><br>
    </div>
    <div submit-success>
      <template type="amp-mustache">
        Success! Mailing a postcard to {{name}}.
      </template>
    </div>
  </form>
</div>

Suggesting rich content

More complicated data can be passed into autocompleted with an array of JsonObjects in "items".

    {
      "items": [{
        "id": 1,
        "img": "/img/product1_640x426.jpg",
        "name": "Apple",
        "price": "1.99",
        "color": "green"
      }, 
      ...
      }]
    }

By default, amp-autocomplete will suggest items by matching on the "value" property of each JsonObject, but for more specified data, an attribute filter-value can be provided to signify the appropriate property to search on.

In the above example, we will want to search on the property name, because that is what the user will most likely search for.

Success!
Error!
<form class="sample-form"
  method="post"
  action-xhr="https://ampbyexample.com/components/amp-form/submit-form-input-text-xhr"
  target="_top">
  <label>
    <span>Search for</span>
    <amp-autocomplete filter="token-prefix"
      filter-value="city"
      min-characters="0">
      <input type="text"
        name="term">
      <script type="application/json">
        {
          "items": [{
            "city": "Albany",
            "state": "New York",
            "areaCode": 518,
            "population": 98251
          }, {
            "city": "Annapolis",
            "state": "Maryland",
            "areaCode": 410,
            "population": 39321
          }, {
            "city": "Trenton",
            "state": "New Jersey",
            "areaCode": 609,
            "population": 84964
          }]
        }
      </script>
      <template type="amp-mustache"
        id="amp-template-custom">
        <div class="city-item"
          data-value="{{city}}, {{state}}">
          <div>{{city}}, {{state}}</div>
          <div class="custom-population">Population: {{population}}</div>
        </div>
      </template>
    </amp-autocomplete>
  </label>
  <input type="submit"
    value="Search">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Default state

Default suggestions for an amp-autocomplete can be displayed on user focus using rich content templating.

Success!
Error!
<div>
  <form class="sample-form"
    method="post"
    action-xhr="https://ampbyexample.com/components/amp-form/submit-form-input-text-xhr"
    target="_top">
    <amp-autocomplete filter="substring"
      min-characters="0"
      [src]="manualFilterData">
      <input type="text"
        on="input-debounced:AMP.setState({ manualFilterData: event.value.length == 0 ? 
          initialInventory : { 'items' : [ 'apple', 'orange', 'banana' ]} })">
      <amp-state id="initialInventory">
        <script type="application/json">
          {
            "items": [{
              "value": "",
              "isInitial": "true",
              "produce": ["apple", "orange", "banana"]
            }]
          }
        </script>
      </amp-state>
      <template type="amp-mustache">
        {{#isInitial}}
          <div data-value="">
            <b>Recommended Fruit</b>
            {{#produce}}
              <div class="trending-fruits">
                <amp-img class="trending"
                  width="24"
                  height="24"
                  src="/static/samples/img/trending.png"></amp-img>
                <span class="trending">{{.}}</span>
              </div>
            {{/produce}}
          </div>
        {{/isInitial}}
        {{^isInitial}}
          <div data-value="{{.}}">
            {{.}}
          </div>
        {{/isInitial}}
      </template>
    </amp-autocomplete>
    <input type="submit"
      value="Search">
    <div submit-success>
      Success!
    </div>
    <div submit-error>
      Error!
    </div>
  </form>
</div>
Need further explanation?

If the explanations on this page don't cover all of your questions feel free to reach out to other AMP users to discuss your exact use case.

Go to Stack Overflow
An unexplained 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.

Edit sample on GitHub