An input element that validates its value against a server endpoint.
$ npm install --save @github/auto-check-element
Import as a modules:
import '@github/auto-check-element'
With a script tag:
<script type="module" src="./node_modules/@github/auto-check-element/dist/index.js">
<auto-check src="/signup-check/username" csrf="<%= authenticity_token_for("/signup-check/username") %>">
<input>
</auto-check>
Note that in the following example the CSRF element is marked with the data-csrf
attribute rather than name
so that the value doesn’t get posted to the backend when the element is placed in a form.
<auto-check src="/signup-check/username">
<input>
<input hidden data-csrf value="<%= authenticity_token_for("/signup-check/username") %>">
</auto-check>
src
is the server endpoint that will receive POST requests. The posted form contains a value
parameter containing the text input to validate. Responding with a 200 OK status indicates the provided value is valid. Any other error status response indicates the provided value is invalid.csrf
is the CSRF token for the posted form. It’s available in the request body as a authenticity_token
form parameter.
required
is a boolean attribute that requires the validation to succeed before the surrounding form may be submitted.http-method
defaults to POST
where data is submitted as a POST with form data. You can set GET
and the HTTP method used will be a get with url encoded params instead.Request lifecycle events are dispatched on the <auto-check>
element. These events do not bubble.
loadstart
- The server fetch has started.load
- The network request completed successfully.error
- The network request failed.loadend
- The network request has completed.Network events are useful for displaying progress states while the request is in-flight.
const check = document.querySelector('auto-check')
const container = check.parentElement
check.addEventListener('loadstart', () => container.classList.add('is-loading'))
check.addEventListener('loadend', () => container.classList.remove('is-loading'))
check.addEventListener('load', () => container.classList.add('is-success'))
check.addEventListener('error', () => container.classList.add('is-error'))
auto-check-start
is dispatched on when there has been input in the element. In event.detail
you can find:
setValidity
: A function to provide a custom failure message on the input. By default it is ‘Verifying…’.const input = check.querySelector('input')
input.addEventListener('auto-check-start', function(event) {
const {setValidity} = event.detail
setValidity('Loading validation')
})
auto-check-send
is dispatched before the network request begins. In event.detail
you can find:
body
: The FormData request body to modify before the request is sent.const input = check.querySelector('input')
input.addEventListener('auto-check-send', function(event) {
const {body} = event.detail
body.append('custom_form_data', 'value')
})
auto-check-success
is dispatched when the server responds with 200 OK. In event.detail
you can find:
response
: The successful server Response. Its body can be used for displaying server-provided messages.input.addEventListener('auto-check-success', async function(event) {
const message = await event.detail.response.text()
console.log('Validation passed', message)
})
auto-check-error
is dispatched when the server responds with a 400 or 500 range error status. In event.detail
you can find:
response
: The failed server Response. Its body can be used for displaying server-provided messages.setValidity
: A function to provide a custom failure message on the input. By default it is ‘Validation failed’.input.addEventListener('auto-check-error', async function(event) {
const {response, setValidity} = event.detail
setValidity('Validation failed')
const message = await response.text()
console.log('Validation failed', message)
})
auto-check-complete
is dispatched after either the success or error events to indicate the end of the auto-check lifecycle.
input.addEventListener('auto-check-complete', function(event) {
console.log('Validation complete', event)
})
Browsers without native custom element support require a polyfill.
npm install
npm test
For local development, uncomment the line at the bottom of examples/index
and serve the page using npx serve
.
Distributed under the MIT license. See LICENSE for details.