Reference

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.

Live example — click to verify

Installation

Load the script once per page, then place the element inside the form you want to protect.

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

AttributeRequiredDescription
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.
HTML
<proofval-widget site-key="YOUR_SITE_KEY" theme="light"></proofval-widget>

What happens on click

  1. The widget requests a challenge from GET /v1/challenge using your site key. The server checks the request origin against the site's allowlist.
  2. 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.
  3. The solution is posted to POST /v1/solved. The server checks it and issues a one-time token valid for 15 minutes.
  4. The widget writes the token into a hidden <input name="proofval-token"> inside the form, switches to "Verified" and fires proofval: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.

Eventevent.detailWhen
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.
JavaScript
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.

MemberTypeDescription
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.
JavaScript
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();
  }
});
Tokens are single-use. If your request fails after the token was consumed by /v1/verify, the visitor needs to verify again before retrying. Reload the page or reset the widget as shown above.

Visible states

StateLabelMeaning
idleClick to verifyWaiting for the visitor.
solvingVerifying…Challenge fetched, worker is searching for a solution.
verifiedVerifiedToken issued and injected into the form.
unverifiedPlease verify firstThe visitor tried to submit before verifying. Clears after 2.5 seconds.
errorVerification failed — retrySomething went wrong; see troubleshooting.
blockedToo many attempts — try again in NsPer-IP rate limit hit; counts down automatically.
quotaVerification unavailableThe 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

SymptomLikely causeFix
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.