{"id":13452159,"url":"https://github.com/github/auto-check-element","last_synced_at":"2025-04-13T15:09:41.602Z","repository":{"id":31867610,"uuid":"128214981","full_name":"github/auto-check-element","owner":"github","description":"An input element that validates its value with a server endpoint.","archived":false,"fork":false,"pushed_at":"2025-03-28T22:13:30.000Z","size":1260,"stargazers_count":179,"open_issues_count":1,"forks_count":34,"subscribers_count":250,"default_branch":"main","last_synced_at":"2025-04-13T15:09:26.512Z","etag":null,"topics":["custom-elements","web-components"],"latest_commit_sha":null,"homepage":"https://github.github.com/auto-check-element/examples/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-05T14:05:49.000Z","updated_at":"2025-04-11T13:26:55.000Z","dependencies_parsed_at":"2024-05-28T20:06:51.804Z","dependency_job_id":"8dd478c4-d1c5-4cdd-86d1-5de6d80b0307","html_url":"https://github.com/github/auto-check-element","commit_stats":{"total_commits":276,"total_committers":12,"mean_commits":23.0,"dds":0.4057971014492754,"last_synced_commit":"ed737b1ff5578ffac0062fd46543dd21905e20a8"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-check-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-check-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-check-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-check-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/auto-check-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732486,"owners_count":21152852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-elements","web-components"],"created_at":"2024-07-31T07:01:15.267Z","updated_at":"2025-04-13T15:09:41.565Z","avatar_url":"https://github.com/github.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# \u0026lt;auto-check\u0026gt; element\n\nAn input element that validates its value against a server endpoint.\n\n## Installation\n\n```\n$ npm install --save @github/auto-check-element\n```\n\n## Usage\n\n### Script\n\nImport as a modules:\n\n```js\nimport '@github/auto-check-element'\n```\n\nWith a script tag:\n\n```html\n\u003cscript type=\"module\" src=\"./node_modules/@github/auto-check-element/dist/index.js\"\u003e\n```\n\n### Markup\n\n```erb\n\u003cauto-check src=\"/signup-check/username\" csrf=\"\u003c%= authenticity_token_for(\"/signup-check/username\") %\u003e\"\u003e\n  \u003cinput\u003e\n\u003c/auto-check\u003e\n```\n\nNote 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.\n\n```erb\n\u003cauto-check src=\"/signup-check/username\"\u003e\n  \u003cinput\u003e\n  \u003cinput hidden data-csrf value=\"\u003c%= authenticity_token_for(\"/signup-check/username\") %\u003e\"\u003e\n\u003c/auto-check\u003e\n```\n\n## Attributes\n\n- `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.\n- `csrf` is the [CSRF][] token for the posted form. It's available in the request body as a `authenticity_token` form parameter.\n  - You can also supply the CSRF token via a child element. See [usage](#Usage) example.\n- `required` is a boolean attribute that requires the validation to succeed before the surrounding form may be submitted.\n- `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.\n\n## Events\n\n### Network request lifecycle events\n\nRequest lifecycle events are dispatched on the `\u003cauto-check\u003e` element. These events do not bubble.\n\n- `loadstart` - The server fetch has started.\n- `load` - The network request completed successfully.\n- `error` - The network request failed.\n- `loadend` - The network request has completed.\n\nNetwork events are useful for displaying progress states while the request is in-flight.\n\n```js\nconst check = document.querySelector('auto-check')\nconst container = check.parentElement\ncheck.addEventListener('loadstart', () =\u003e container.classList.add('is-loading'))\ncheck.addEventListener('loadend', () =\u003e container.classList.remove('is-loading'))\ncheck.addEventListener('load', () =\u003e container.classList.add('is-success'))\ncheck.addEventListener('error', () =\u003e container.classList.add('is-error'))\n```\n\n### Auto-check events\n\n**`auto-check-start`** is dispatched on when there has been input in the element. In `event.detail` you can find:\n\n- `setValidity`: A function to provide a custom failure message on the input. By default it is 'Verifying…'.\n\n\n```js\nconst input = check.querySelector('input')\n\ninput.addEventListener('auto-check-start', function(event) {\n  const {setValidity} = event.detail\n  setValidity('Loading validation')\n})\n```\n\n**`auto-check-send`** is dispatched before the network request begins. In `event.detail` you can find:\n\n- `body`: The FormData request body to modify before the request is sent.\n\n\n```js\nconst input = check.querySelector('input')\n\ninput.addEventListener('auto-check-send', function(event) {\n  const {body} = event.detail\n  body.append('custom_form_data', 'value')\n})\n```\n\n**`auto-check-success`** is dispatched when the server responds with 200 OK. In `event.detail` you can find:\n\n- `response`: The successful server [Response][]. Its body can be used for displaying server-provided messages.\n\n```js\ninput.addEventListener('auto-check-success', async function(event) {\n  const message = await event.detail.response.text()\n  console.log('Validation passed', message)\n})\n```\n\n**`auto-check-error`** is dispatched when the server responds with a 400 or 500 range error status. In `event.detail` you can find:\n\n- `response`: The failed server [Response][]. Its body can be used for displaying server-provided messages.\n- `setValidity`: A function to provide a custom failure message on the input. By default it is 'Validation failed'.\n\n```js\ninput.addEventListener('auto-check-error', async function(event) {\n  const {response, setValidity} = event.detail\n\n  setValidity('Validation failed')\n\n  const message = await response.text()\n  console.log('Validation failed', message)\n})\n```\n\n**`auto-check-complete`** is dispatched after either the success or error events to indicate the end of the auto-check lifecycle.\n\n```js\ninput.addEventListener('auto-check-complete', function(event) {\n  console.log('Validation complete', event)\n})\n```\n\n[CSRF]: https://en.wikipedia.org/wiki/Cross-site_request_forgery\n[Response]: https://developer.mozilla.org/en-US/docs/Web/API/Response\n\n## Manually Trigger Validation\n\nThe `triggerValidation()` function can be used to manually trigger the `\u003cauto-check\u003e` element.\n\n```js\ndocument.getElementById('input-element').closest('auto-check').triggerValidation()\n```\n\n## Browser support\n\nBrowsers without native [custom element support][support] require a [polyfill][].\n\n- Chrome\n- Firefox\n- Safari\n- Microsoft Edge\n\n[support]: https://caniuse.com/#feat=custom-elementsv1\n[polyfill]: https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements\n\n## Development\n\n```\nnpm install\nnpm test\n```\n\nFor local development, uncomment the line at the bottom of `examples/index` and serve the page using `npx serve`.\n\n## License\n\nDistributed under the MIT license. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fauto-check-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fauto-check-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fauto-check-element/lists"}