Methods
The custom element exposes a small JavaScript API for explicit form control.
| Method | Returns | Purpose |
|---|---|---|
| solve() | Promise<{ success: boolean, token: string }> | Starts solving, reuses an in-flight solve, or returns the existing token result. |
| reset() | void | Clears the current token, resets the hidden field, and returns the widget to idle. |
Events
| Event | Detail | When it fires |
|---|---|---|
| solve | { token } | A challenge was solved and the hidden field was filled. |
| progress | Challenge progress payload | The underlying challenge runtime reports solving progress. |
| error | Error payload or reason | Solving failed, billing blocked the request, the limit was reached, or the widget fallback reported a load failure. |
| reset | {} | The widget was reset and the hidden field was cleared. |
| expired | {} | The token expired after data-expire-after and must be solved again. |
const widget = document.querySelector('human-proof');
widget.addEventListener('solve', (event) => {
console.log(event.detail.token);
});
widget.addEventListener('expired', () => {
submit.disabled = true;
});
widget.addEventListener('error', (event) => {
console.warn(event.detail);
});Global events
The script dispatches humanproof:ready when the custom elements are registered and humanproof:failed when the browser cannot initialize the runtime.
window.addEventListener('humanproof:ready', (event) => {
console.log(event.detail.version);
});
window.addEventListener('humanproof:failed', (event) => {
console.warn(event.detail.reason);
});Watchdog
HumanProof.watchdog() can show a plain fallback message if a consent manager, browser extension, or corporate gateway prevents the widget from initializing.
<script>
window.addEventListener('humanproof:ready', () => {
window.HumanProof.watchdog({ timeout: 3000 });
});
</script>