#BlackLivesMatter
Do you build things with AMP? Fill out the new AMP Developer Survey!
AMP

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

amp-autocomplete

Description

Usage

Required Scripts

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

Supported Layouts

Usage

The amp-autocomplete extension should be used for suggesting completed items based on user input to help users carry out their task more quickly.

This component is currently experimental in the AMP for Email format as email clients add support for the feature. Until the component is publicly available in the format, you will notice the component is in some cases valid and sendable in emails but may be only functioning in its fallback behavior capacity across email clients as well as in their respective playgrounds. The fallback for the component does not display autocomplete suggestions, and will behave as the unenhanced input or textarea field it is given.

This can be used to power search experiences, in cases where the user may not know the full range of potential inputs, or in forms to help ensure inputs where there may be multiple ways to express the same intent (using a state abbreviation instead of its full name, for example) yield more predictable results.

Example:

<amp-autocomplete
  filter="substring"
  id="myAutocomplete"
  src="/static/samples/json/amp-autocomplete-cities.json"
>
  <input />
</amp-autocomplete>

Attributes

src

The URL of the remote endpoint that returns the JSON that will be filtered and rendered within this amp-autocomplete. This must be a CORS HTTP service and the URL's protocol must be HTTPS. The endpoint must implement the requirements specified in the CORS Requests in AMP spec. If fetching the data at the src URL fails, the amp-autocomplete triggers a fallback. The src attribute may be omitted if the [src] attribute exists.

query

The query parameter to generate a static remote endpoint that returns the JSON that will be filtered and rendered within this amp-autocomplete. This requires the presence of the src attribute. For example, if src="http://www.example.com" and query="q", then when a user types in abc, the component will retrieve data from http://www.example.com?q=abc.

min-characters

The min character length of a user input to provide results, default 1

max-items

The max specified number of items to suggest at once based on a user input, displays all if unspecified

suggest-first

Suggest the first entry in the list of results by marking it active; only possible if filter==prefix (does nothing otherwise)

submit-on-enter

The enter key is primarily used for selecting suggestions in autocomplete, so it shouldn’t also submit the form unless the developer explicitly sets it to do so (for search fields/one field forms, et cetera).

The user flow is as follows: If submit-on-enter is true, pressing Enter will select any currently active item and engage in default behavior, including submitting the form if applicable. If submit-on-enter is false, pressing Enter while suggestions are displaying will select any currently active item only and prevent any other default behavior. If suggestions are not displaying, autocomplete allows default behavior. Defaults to false.

highlight-user-entry

If present, exposes the autocomplete-partial class on the substring within the suggested item that resulted in its match with the user input. This can be used to stylize the corresponding match to stand out to the user. Defaults to false.

items

Specifies the key to the data array within the JSON response. Nested keys can be expressed with a dot-notated value such as field1.field2. The default value is "items". The following are examples with and without usage:


  <amp-autocomplete filter="prefix">
      <input type="text">
      <script type=application/json>
        { "items" : ["apples", "bananas", "pears"] }
       </script>

  </amp-autocomplete>

  <amp-autocomplete filter="prefix" items="fruit">
    <input type="text">
    <script type=application/json>
      { "fruit" : ["apples", "bananas", "pears"] }
      </script>
  </amp-autocomplete>

In the first example, the JSON payload is queued by the "items" key, and thus no component attribute is needed because the default value corresponds. In the second example, the JSON payload is queued by the "fruit" key, so the items attribute is given the value "fruit" so as to accurately etrieve the intended datasource. In both examples, the end user interaction is the same.

inline

Whether the amp-autocomplete should autosuggest on the full user input or only a triggered substring of the user input. By default when the attribute is absent, suggestions will be based on the full user input. The attribute cannot have an empty value but must take a single character token, i.e. @ which activates the autocomplete behavior. For example, if inline="@" then user input of hello will not retrieve suggestions but a user input of hello @abc might trigger options filtered on the substring abc. Currently triggered substrings are delimited on whitespace characters, however this is subject to change in the future.

Events

select

amp-autocomplete triggers the select event when the user selects an option via click, tap, keyboard navigation or accepting typeahead. It also fires the select event if a user keyboard navigates to an item and Tabs away from the input field. event contains the value attribute value of the selected element.

Validation

See amp-autocomplete rules in the AMP validator specification.

هل تحتاج إلى مزيد من المساعدة؟

لقد قرأت هذا المستند عشرات المرات ولكن ألم يُجِب عن جميع أسئلتك؟ ربما حصل ذات الأمر مع أشخاص آخرين: تواصل معهم على Stack Overflow.

الذهاب إلى Stack Overflow
هل وجدت خطأ أو تفتقد لميزة؟

يشجع مشروع AMP مشاركتك ومساهمتك بشدة! ونأمل أن تكون مشاركًا دائمًا في مجتمعنا مفتوح المصدر، ولكننا نشجع أيضًا المساهمات التي تحدث لمرة واحدة في الأمور التي تتحمس لها.

الانتقال إلى GitHub