- amp-form
- Introduction Setup Form submission with page reload Form submission with client-side rendering Form custom validation Form verification Reset / clear form input Hiding input fields after a successful submission Input type=date Input type=month Input type=week Input type=datetime-local Input type=time Input type=checkbox Input type=email Input type=hidden Input type=number Input type=radio Input type=range Input type=tel Input type=url Input type=password Input select
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>
Se as explicações nesta página não respondem a todas as suas perguntas, entre em contato com outros usuários de AMP para discutir seu caso de uso específico.
Ir para o Stack Overflow Falta explicar algum recurso?O projeto AMP incentiva fortemente sua participação e contribuições! Esperamos que você se torne um participante assíduo de nossa comunidade de código aberto, mas também agradecemos contribuições pontuais para problemas que você tenha particular interesse.
Editar amostra no GitHub-
Written by @kul3r4