Widget
<proofval-widget> is a self-contained custom element. It fetches a challenge,
solves it in a Web Worker, injects the resulting one-time token into the surrounding form and
blocks submission until that has happened.
Installation
Load the script once per page, then place the element inside the form you want to protect.
<script src="https://www.proofval.com/v1/widget.js" async></script>
<form method="post">
...
<proofval-widget site-key="YOUR_SITE_KEY"></proofval-widget>
<button type="submit">Submit</button>
</form>
The script can be loaded with async or defer. It registers the element
when it runs, so the widget appears as soon as the script has loaded even if the HTML was parsed
earlier. The widget renders inside a Shadow DOM, so your page styles do not affect it and its
styles do not leak into your page.
Attributes
| Attribute | Required | Description |
|---|---|---|
site-key |
Yes | The public site key from the dashboard. Without it the widget shows an error on click. |
theme |
No | dark (default) or light. Pick the one that matches your form's background. |
api-base |
No | Origin to call for challenges and tokens. Defaults to the origin the script was loaded from, which is what you want in almost every case. |
<proofval-widget site-key="YOUR_SITE_KEY" theme="light"></proofval-widget>
What happens on click
- The widget requests a challenge from
GET /v1/challengeusing your site key. The server checks the request origin against the site's allowlist. - A Web Worker searches for a SHA-256 hash with the required number of leading zero bits. This runs off the main thread, so the page stays responsive. It typically finishes in a fraction of a second.
- The solution is posted to
POST /v1/solved. The server checks it and issues a one-time token valid for 15 minutes. - The widget writes the token into a hidden
<input name="proofval-token">inside the form, switches to "Verified" and firesproofval:verified.
Your server then exchanges the token for a result with POST /v1/verify. That part is
covered in Server verification.
Form integration
The widget finds its closest <form> ancestor and guards it. Until the visitor
has verified, it cancels the form's submit event and clicks on submit buttons,
shows "Please verify first" for a couple of seconds, and then returns to the idle state.
The guard runs in the capture phase, so it works even when your own submit handler was registered
first.
Once verified, the form submits normally and your backend receives the token in the
proofval-token field alongside the other fields. If the widget is not inside a form,
nothing is injected or blocked. Use the JavaScript API to read the token yourself.
Events
All events are CustomEvents that bubble and cross the Shadow DOM boundary, so you can
listen on the element, the form, or document.
| Event | event.detail | When |
|---|---|---|
proofval:verified |
{ token } |
The visitor has verified and the token has been placed in the form. |
proofval:error |
{} |
Verification failed: missing site key, network error, rejected solution, origin not allowed, or an automated browser was detected. The widget shows a retry link. |
proofval:blocked |
{ retryAfter } |
The visitor hit the per-IP rate limit. The widget counts down retryAfter seconds and then returns to idle. |
proofval:quota |
{ message } |
The site has used its monthly verification quota. No retry will help until the plan is upgraded or the month rolls over. |
document.addEventListener('proofval:verified', (event) => {
console.log('token:', event.detail.token);
document.querySelector('#send').disabled = false;
});
document.addEventListener('proofval:quota', (event) => {
console.warn('ProofVal quota reached:', event.detail.message);
});
JavaScript API
For forms that are submitted with fetch() instead of a classic POST, read the token
from the element and send it along with your payload.
| Member | Type | Description |
|---|---|---|
widget.token |
string | undefined |
The current one-time token, or undefined before verification. |
widget.verified |
boolean |
true once the visitor has verified. |
widget.whenVerified() |
Promise<string> |
Resolves with the token as soon as verification completes. Resolves immediately if already verified. |
const form = document.querySelector('#contact-form');
const widget = form.querySelector('proofval-widget');
form.addEventListener('submit', async (event) => {
event.preventDefault();
// Wait for the visitor to click the widget if they have not yet.
const token = await widget.whenVerified();
const payload = Object.fromEntries(new FormData(form));
payload['proofval-token'] = token;
const response = await fetch('/api/contact', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
if (!response.ok) {
// Ask the visitor to verify again: each token is single-use.
widget.__retryFromError();
}
});
/v1/verify, the visitor needs to verify again before retrying. Reload the page or
reset the widget as shown above.
Visible states
| State | Label | Meaning |
|---|---|---|
idle | Click to verify | Waiting for the visitor. |
solving | Verifying… | Challenge fetched, worker is searching for a solution. |
verified | Verified | Token issued and injected into the form. |
unverified | Please verify first | The visitor tried to submit before verifying. Clears after 2.5 seconds. |
error | Verification failed — retry | Something went wrong; see troubleshooting. |
blocked | Too many attempts — try again in Ns | Per-IP rate limit hit; counts down automatically. |
quota | Verification unavailable | The site's monthly limit is reached. |
Theming and layout
The widget is a fixed-height inline box that stretches to the width of its container. Wrap it in
a block element to control spacing, exactly as you would an input. Use theme="light"
on light backgrounds. Because it renders in a Shadow DOM, there are no CSS hooks to restyle its
internals.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Error immediately on click, console says "Missing site-key attribute" | The site-key attribute is empty or misspelled. |
Copy the site key from the dashboard into the attribute. |
Error on click, network tab shows 403 with origin_not_allowed |
The page's origin is not in the site's allowlist. | Add the exact origin, scheme and host, no path or trailing slash, in the dashboard. http://localhost:3000 and https://example.com are different origins. |
| Error in automated tests, console says "Automated environment detected" | The widget refuses to run under WebDriver or headless browsers. | Stub the token in end-to-end tests, or test the integration through the verify API directly. |
| Widget never appears | The script is blocked, or the element is rendered before the script and a framework re-renders it without the custom element upgrading. | Check the network tab for /v1/widget.js. Make sure the element has not been renamed by a bundler or sanitizer. |
| Form submits but your server rejects the token | The token was already used, expired, or verified against the wrong site's secret key. | See the error table in Server verification. |