Repository files navigation

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:

<scripttype="module"src="./node_modules/@github/auto-check-element/dist/index.js">

<auto-checksrc="/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 thedata-csrf attribute rather thanname so that the value doesn't get posted to the backend when the element is placed in a form.

<auto-checksrc="/signup-check/username"><input><inputhiddendata-csrfvalue="<%=authenticity_token_for("/signup-check/username")%>"></auto-check>

• src is the server endpoint that will receive POST requests. The posted form contains avalue 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 theCSRF token for the posted form. It's available in the request body as aauthenticity_token form parameter.
  • You can also supply the CSRF token via a child element. Seeusage example.
• required is a boolean attribute that requires the validation to succeed before the surrounding form may be submitted.
• http-method defaults toPOST where data is submitted as a POST with form data. You can setGET 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.

constcheck=document.querySelector('auto-check')constcontainer=check.parentElementcheck.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. Inevent.detail you can find:

• setValidity: A function to provide a custom failure message on the input. By default it is 'Verifying…'.

constinput=check.querySelector('input')input.addEventListener('auto-check-start',function(event){const{setValidity}=event.detailsetValidity('Loading validation')})

auto-check-send is dispatched before the network request begins. Inevent.detail you can find:

• body: The FormData request body to modify before the request is sent.

constinput=check.querySelector('input')input.addEventListener('auto-check-send',function(event){const{body}=event.detailbody.append('custom_form_data','value')})

auto-check-success is dispatched when the server responds with 200 OK. Inevent.detail you can find:

• response: The successful serverResponse. Its body can be used for displaying server-provided messages.

input.addEventListener('auto-check-success',asyncfunction(event){constmessage=awaitevent.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. Inevent.detail you can find:

• response: The failed serverResponse. 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',asyncfunction(event){const{response, setValidity}=event.detailsetValidity('Validation failed')constmessage=awaitresponse.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)})

ThetriggerValidation() function can be used to manually trigger the<auto-check> element.

document.getElementById('input-element').closest('auto-check').triggerValidation()

Browsers without nativecustom element support require apolyfill.

• Chrome
• Firefox
• Safari
• Microsoft Edge

npm installnpm test

For local development, uncomment the line at the bottom ofexamples/index and serve the page usingnpx serve.

Distributed under the MIT license. See LICENSE for details.