websites

amp-form

Introduction

The amp-form extension allows the usage of forms and input fields in an AMP document. amp-form allows HTTP and XHR (XMLHttpRequest) form submissions. An HTTP form submission loads a new page, while an XHR form submission doesn't require a page reload.

The amp-form extension also allows you to render success and error responses with the submit-success and submit-error special attributes. For details on usage, see the amp-form documentation on Success/Error response rendering.

Setup

Import the amp-form extension.

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

amp-mustache is needed for client-side rendering of form responses.

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

Form submission with page reload

Use the action attribute to specify a server-endpoint which should handle the form input. This works only for GET requests. The URL must be HTTPS. The following sample uses type="search" to emulate a search. The search button will trigger a page reload.

Read security considerations for best practices when to use GET or POST.

You can find the code for the server endpoint used in this demo at /examples/api/amp-form.js.

<form class="sample-form" method="GET" action="/documentation/examples/api/submit-form" target="_top">
  <input type="search" placeholder="Search..." name="search">
  <input type="submit" value="OK">
</form>

Form submission with client-side rendering

Use the action-xhr attribute to submit the form via XMLHttpRequest (XHR). You can use amp-mustache templates to client side render the POST response. It's possible to show custom success or error messages, using data sent by the server endpoint as JSON. For example, if the server sends {"foo": "bar"}, you can use use {{foo}} in the template to render bar.

The amp-form component displays submit-success or submit-error elements based on the response and renders the template data inside these two elements. The submit-success and submit-error elements must be direct children of form.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top">
  <input type="text" name="name" placeholder="Name..." required>
  <input type="email" name="email" placeholder="Email..." required>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo with an error response.
    </template>
  </div>
</form>

Form custom validation

The amp-form extension allows you to build your own custom validation UI by using the custom-validation-reporting, read here about the different strategies.

Use show-all-on-submit strategy to ensure all the validation messages are shown when the user submits the form.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="show-all-on-submit">
  <input type="text" id="show-all-on-submit-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="show-all-on-submit-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="show-all-on-submit-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="show-all-on-submit-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="show-all-on-submit-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="show-all-on-submit-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo.
    </template>
  </div>
</form>

Use show-first-on-submit strategy to show the first validation message when the user submit the form.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="show-first-on-submit">
  <input type="text" id="show-first-on-submit-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="show-first-on-submit-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="show-first-on-submit-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="show-first-on-submit-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="show-first-on-submit-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="show-first-on-submit-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo with an error response.
    </template>
  </div>
</form>

Use as-you-go strategy to show validation messages as the user is interacting with the form.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="as-you-go">
  <input type="text" id="as-you-go-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="as-you-go-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="as-you-go-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="as-you-go-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="as-you-go-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="as-you-go-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Form verification

Form verification enables asynchronous validation of form fields. As a user fills out a form with verification enabled, amp-form sends the fields to the verify-xhr URL to check their values using logic on the server. If an error is found, such as a username being taken, it will show as a validation error in the form. Read here for complete documentation.

Use the verify-xhr attribute to enable the form verification feature.

Form verification can combine with custom error reporting using visible-when-invalid="customError". When amp-form receives errors from the XHR response, it sets the customError validity on offending elements. Since AMP uses the HTML5 Form Constraint Validation API, it is easy for form verification errors to interact with standard form validation messages.

In the submit-error template, you can choose how to render verification error message using the verifyErrors list. These will only display if the user submits the form before the asynchronous verification response completes.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/verify-form-input-text-xhr" verify-xhr="/documentation/examples/api/verify-form-input-text-xhr" target="_top" custom-validation-reporting="as-you-go">
  <input type="text" id="verification-username" name="username" placeholder="Username..." required pattern="\w+">
  <span visible-when-invalid="customError" validation-for="verification-username">That username is already taken</span>
  <span visible-when-invalid="patternMismatch" validation-for="verification-username">Invalid character in username</span>
  <input type="submit" value="Check">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      {{#verifyErrors}}
      <p>{{message}}</p>
      {{/verifyErrors}}
      {{^verifyErrors}}
      <p>Something went wrong. Try again later?</p>
      {{/verifyErrors}}
      <p>Submission failed</p>
    </template>
  </div>
</form>

Reset / clear form input

You can use either an <input type="reset"> or the clear action for clearing input fields.

<form class="sample-form" id="formResetSample" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="text" placeholder="Some text...">
  <input type="submit" value="OK">
  <input type="reset" value="Reset">
  <button type="button" on="tap:formResetSample.clear">Clear input</button>
</form>

Hiding input fields after a successful submission

Use the amp-form-submit-success class to hide input fields after a successful submission. The following CSS rule hides all form input fields after successful form submission:

form.amp-form-submit-success > input {
  display: none
}

<form class="sample-form hide-inputs" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top">
  <input type="text" name="name" placeholder="Name..." required>
  <input type="submit" value="Subscribe">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=date

amp-form supports all HTML5 form types with the exception of file and image. It's recommended to use the amp-date-picker component for input fields that should contain a date.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-date" type="date" value="2020-12-30">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=month

Use type="month" for input fields that should contain a month.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-month" type="month" value="2020-12">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
   Error!
  </div>
</form>

Input type=week

Use type="week" for input fields that should contain a week.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="week" name="week_year">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=datetime-local

Use type="datetime-local" for input fields that should contain a date and time.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-datetime" type="datetime-local" value="2020-12-30T12:34:56">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=time

Use type="time" for input fields that should contain a time.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="time" name="time_now">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=checkbox

Use type="checkbox" to let the user select ZERO or MORE options of a limited number of choices.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="checkbox" id="animal1" name="animal1" value="Cats">
  <label for="animal1">I like cats</label>
  <input type="checkbox" id="animal2" name="animal2" value="Dogs">
  <label for="animal2"> I like dogs </label>
  <button type="submit" value="OK">OK</button>
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=email

Use type="email" for input fields that should contain an e-mail address.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="email" name="email" placeholder="Email...">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=hidden

Use type="hidden" to define a field not visible to a user.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="hidden" name="city" value="London">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=number

Use type="number" for input fields that should contain a numeric value.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="number" name="quantity" min="1" max="5">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=radio

Use type="radio" to let a user select ONLY ONE of a limited number of choices.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="radio" id="cat" name="favourite animal" value="cat" checked>
  <label for="cat">Cat</label>
  <input type="radio" id="dog" name="favourite animal" value="dog">
  <label for="dog">Dog</label>
  <input type="radio" id="other" name="favourite animal" value="other">
  <label for="other">Other</label>
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=range

Use type="range" for input fields that should contain a value within a range.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="range" name="points" min="0" max="10">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=tel

Use type="tel" for input fields that should contain a telephone number.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="tel" name="my_tel" placeholder="Telephone...">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=url

Use type="url" for input fields that should contain a URL address.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="url" placeholder="URL..." name="website">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input type=password

Use type="password" for hidden text inputs inside secure POST forms.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="password" placeholder="Password..." name="pw">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

Input select

Use select element for dropdowns.

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <select name="cars" id="cars">
    <option value="volvo">Volvo</option>
    <option value="saab">Saab</option>
    <option value="fiat">Fiat</option>
    <option value="audi">Audi</option>
  </select>
  <label for="cars">Select a car</label>
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

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

Written by @kul3r4