Events

The <ribaunt-widget> emits four DOM custom events — verify, error, state-change, and solver-backend — that you can listen to with addEventListener on the element. In React, use the typed callback props instead of addEventListener; the wrapper wires up and tears down listeners for you automatically.

`verify`

The verify event is dispatched when the widget successfully solves all challenges and, if you provided a verify-endpoint, the server confirms the solutions are valid. If no verify-endpoint is set, the event fires as soon as local proof-of-work is complete. Event type: CustomEvent<{ solutions: ChallengeSolution[]; phase: 'done'; progress: 100 }> Where ChallengeSolution = { nonce: string; hash: string }.

widget.addEventListener('verify', (event) => {
  const { solutions } = event.detail;
  console.log('Verified! Solutions:', solutions);
  // Enable submit button, proceed with form, etc.
});

React equivalent: onVerify={(detail) => ...}

`error`

The error event is dispatched when the widget encounters a failure at any stage — fetching tokens from your challenge endpoint, running the proof-of-work solver, or receiving a non-OK response from your verify endpoint. Event type: CustomEvent<{ error: string; code: WidgetErrorCode; timeout: boolean; phase: 'error' }> The code field is a stable, machine-readable identifier you can branch on:

Code	Meaning
`timeout`	The attempt exceeded the configured `solve-timeout`. Covers fetching, solving, and verifying.
`aborted`	Solving was cancelled (e.g. widget reset).
`challenge-fetch-failed`	Request to the challenge endpoint failed.
`invalid-challenge`	Challenge response had an unexpected shape.
`solve-failed`	Solver could not find a valid nonce.
`verification-failed`	Server verify endpoint rejected the solution.
`worker-unavailable`	Web Worker solver is not available and `worker-mode="required"` is set.
`unknown`	Unclassified error.

widget.addEventListener('error', (event) => {
  const { error, code, timeout } = event.detail;
  if (timeout) {
    console.warn('Timed out:', error);
  } else {
    console.error('CAPTCHA failed:', error, code);
  }
});

React equivalent: onError={(detail) => ...}

The timeout field is always present in the event detail. It is true only when solve-timeout is configured and the attempt exceeded that limit; for every other error it is false.

`state-change`

The state-change event is dispatched every time the widget transitions between internal states. You can use this to mirror the widget’s visual state in your own UI — for example, disabling a submit button while verification is in progress. Event type: CustomEvent<{ state: WidgetState; phase: WidgetState; progress: number }>

widget.addEventListener('state-change', (event) => {
  const { state, progress } = event.detail;
  console.log('Widget state:', state, progress);
});

React equivalent: onStateChange={(detail) => ...}

`solver-backend`

The solver-backend event is dispatched once per solve request when the worker selects its solving backend: wasm when the WebAssembly SHA-256 solver loaded, js when WASM is disabled or unavailable, or argon2id when the challenge tokens use the memory-hard Argon2id algorithm. Use it for adoption telemetry or to confirm your wasm-mode configuration takes effect. The detail never includes challenge contents, nonces, or hashes. Event type: CustomEvent<{ backend: 'wasm' | 'js' | 'argon2id'; phase: 'solving' }>

widget.addEventListener('solver-backend', (event) => {
  console.log('Solver backend:', event.detail.backend);
});

The event only fires when solving runs inside a Web Worker. When worker-mode="preferred" falls back to main-thread solving, no solver-backend event is emitted. The worker detects the algorithm from the challenge tokens themselves, so argon2id is reported automatically whenever your server issues Argon2id challenges. wasm-mode does not affect this selection; it only controls the SHA-256 solver. React equivalent: listen via onEvent or addEventListener on the element ref.

React callback props

When you use the React wrapper, you can pass all callbacks directly as props. The wrapper maintains stable event listener references across re-renders so your callbacks always receive the latest closure values:

<RibauntWidget
  challengeEndpoint="/api/captcha/challenge"
  verifyEndpoint="/api/captcha/verify"
  onVerify={(detail) => console.log('Solutions:', detail.solutions)}
  onError={(detail) => console.error('Error:', detail.error)}
  onStateChange={(detail) => console.log('State:', detail.state)}
  onReady={(detail) => console.log('Ready with state:', detail.state)}
  onLoad={(detail) => console.log('Widget loaded:', detail.state)}
  onEvent={(type, detail) => console.log('Event:', type, detail)}
/>

React-only events

Three additional callbacks are available in the React wrapper that have no corresponding DOM custom event on the web component:

onReady — fires once after the widget mounts, with the initial widget state in the detail payload. Use this to know when the widget is ready for interaction.
onLoad — functionally identical to onReady. It is provided as an alias for backward compatibility if you were already using onLoad in an earlier version.
onEvent — a catch-all handler that fires for every event type ('verify', 'error', 'state-change', 'solver-backend', and 'ready'), along with the event’s detail object. Use this if you want a single place to handle or log all widget events.

The widget moves through a defined set of states during its lifecycle. You will encounter these state strings in state-change events and in the return value of getState():

State	Description
`initial`	Widget has loaded, waiting for user click or auto-verify
`fetching`	The widget is requesting challenges
`solving`	The solver is running proof-of-work
`verifying`	The widget is posting solutions to your verify endpoint
`done`	Challenge solved and verified successfully
`error`	An error occurred during fetch, solve, or verify

Get Started

Core Concepts

Server Setup

Frontend Integration

Widget

Guides

`verify`

`error`

`state-change`

`solver-backend`

React callback props

React-only events

Widget states

​verify

​error

​state-change

​solver-backend

​React callback props

​React-only events

​Widget states

`verify`

`error`

`state-change`

`solver-backend`

React callback props

React-only events

Widget states