@github/auto-check-element

中文文档
6.0.0发布于 2025/03/26MITTypeScriptES Module近 30 天下载 13.1万

An input element that validates its value with a server endpoint.

原始使用文档
文档目录12 节
  1. Installation
  2. Usage
  3. Script
  4. Markup
  5. Attributes
  6. Events
  7. Network request lifecycle events
  8. Auto-check events
  9. Manually Trigger Validation
  10. Browser support
  11. Development
  12. License

<auto-check> element

An input element that validates its value against a server endpoint.

Installation

$ npm install --save @github/auto-check-element

Usage

Script

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">

Markup

<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>

Attributes

  • 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.
    • You can also supply the CSRF token via a child element. See usage example.
  • 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.

Events

Network request lifecycle events

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 events

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)
})

Manually Trigger Validation

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

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

Browser support

Browsers without native custom element support require a polyfill.

  • Chrome
  • Firefox
  • Safari
  • Microsoft Edge

Development

npm install
npm test

For local development, uncomment the line at the bottom of examples/index and serve the page using npx serve.

License

Distributed under the MIT license. See LICENSE for details.

版本与发布记录

@github/auto-check-element 共发布 25 个版本,首次发布于 2019/05/23;过去 12 个月发布了 0 个版本。

版本发布日期距今
6.0.0latest2025/03/261.6 年前
5.6.02025/01/141.8 年前
5.5.12024/12/121.9 年前
5.5.02024/11/272 年前
5.4.22024/05/302 年前
5.4.12023/07/053 年前

其他发布通道:beta → 5.1.2-0。

关于 @github/auto-check-element 的常见问题

@github/auto-check-element 是什么?

An input element that validates its value with a server endpoint.

如何安装 @github/auto-check-element?

在项目目录运行 npm install @github/auto-check-element,或使用 pnpm add / yarn add / bun add。

@github/auto-check-element 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@github/auto-check-element 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@github/auto-check-element 可以商用吗?

@github/auto-check-element 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@github/auto-check-element 的下载量有多少?

根据 npm 官方下载统计,@github/auto-check-element 在 2026/10/17 – 2026/11/15 这 30 天内被下载 130,673 次,日均约 4,356 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@github/auto-check-element 还在维护吗?

最新版本 6.0.0 发布于 2025/03/26(1.6 年前);至今共发布 25 个版本,其中过去 12 个月发布了 0 个;首次发布于 2019/05/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。