Configuration

The <ribaunt-widget> Web Component and its React wrapper share the same configuration surface. HTML uses kebab-case attributes; React uses camelCase props. You can use both interchangeably depending on your stack — everything described here applies to both unless noted otherwise.

Quick example

The snippet below shows the most commonly used attributes on the HTML element:

<ribaunt-widget
  challenge-endpoint="/api/captcha/challenge"
  verify-endpoint="/api/captcha/verify"
  auto-verify="true"
  show-warning="false"
  warning-message="Verification may take longer on this device."
  solve-timeout="15000"
  worker-mode="preferred"
  wasm-mode="preferred"
  challenge-method="GET"
  calibrate="true"
  disabled="false"
></ribaunt-widget>

Attribute & prop reference

HTML Attribute	React Prop	Type	Default	Description
`challenge-endpoint`	`challengeEndpoint`	`string`	`undefined`	URL endpoint that returns `{ challenges: string[] }`. If undefined, the widget cannot auto-fetch.
`verify-endpoint`	`verifyEndpoint`	`string`	`undefined`	URL endpoint to POST the solutions. If undefined, you must handle verification manually using the solver directly.
`auto-verify`	`autoVerify`	`boolean	string`	`false`	Starts verification automatically once the widget loads.
`show-warning`	`showWarning`	`boolean	string`	`false`	Shows a warning banner above the widget.
`warning-message`	`warningMessage`	`string`	`"Enable WASM for significantly faster solving"`	Custom message text for the warning banner.
`solve-timeout`	`solveTimeout`	`number	string`	`undefined`	Optional timeout in milliseconds for the whole verification attempt: fetching, solving, and verifying. Omit to leave the attempt un-timed.
`worker-mode`	`workerMode`	`‘preferred'	'required'	'disabled’`	`'preferred'`	Controls Web Worker solving. `preferred` falls back to main-thread solving when workers are unavailable; `required` fails with the `worker-unavailable` error code; `disabled` always solves on the main thread. Unknown values fall back to `preferred` with a console warning.
`wasm-mode`	`wasmMode`	`‘preferred'	'disabled’`	`'preferred'`	Controls the WebAssembly batch solver inside the worker. `preferred` uses WASM when it loads and falls back to the JavaScript solver otherwise; `disabled` always uses the JavaScript solver. Unknown values fall back to `preferred` with a console warning. See WASM solver.
`challenge-method`	`challengeMethod`	`‘GET'	'POST’`	`'GET'`	Chooses how the widget requests challenges. Use `POST` to send a calibration payload for `difficulty: "auto"`.
`calibrate`	`calibrate`	`boolean	string`	`false`	Sends `{ calibration }` in the POST challenge request when `challenge-method="POST"`.
`show-progress`	`showProgress`	`boolean	string`	`true`	Set to `"false"` to switch to the secondary loader: a plain bars spinner with a static `Loading...` label instead of the conic progress ring and percentage counter. Progress is still reported through events.
`disabled`	`disabled`	`boolean	string`	`false`	Disables interaction and prevents automatic verification while set.

Challenge endpoint response format

Your challenge-endpoint should return a JSON body containing the challenge tokens that the widget will solve. The recommended response shape is { challenges: string[] }.

The widget accepts three response formats from challenge-endpoint:

{ challenges: string[] } — recommended contract
{ tokens: string[] } — compatibility support
raw string[] — compatibility support

Invalid or mixed-type token arrays will fail fast with a clear widget error event.

Adaptive difficulty (calibration)

For adaptive workloads, set challenge-method="POST" and calibrate="true". The widget then benchmarks the browser and sends the result as { calibration } in the POST body. Your challenge endpoint forwards the calibration to createChallenge({ difficulty: 'auto', calibration }), letting the server pick a difficulty and amount that fit the user’s device — while never lowering the server-owned baseline.

<ribaunt-widget
  challenge-endpoint="/api/captcha/challenge"
  verify-endpoint="/api/captcha/verify"
  challenge-method="POST"
  calibrate="true"
  auto-verify="true"
></ribaunt-widget>

See createChallenge for the server-side options.

Verification request body

When you provide a verify-endpoint, the widget sends a JSON payload shaped like this:

{
  "tokens": ["jwt-token-1", "jwt-token-2"],
  "solutions": [{ "nonce": "123", "hash": "abc123" }]
}

WASM solver

The widget ships with a WebAssembly-backed SHA-256 batch solver that hashes in larger batches than the JavaScript solver, increasing solve throughput. With the default wasm-mode="preferred", the solver worker attempts to load the bundled .wasm binary and uses it when it initializes successfully. If WebAssembly is disabled, the asset fails to load, or instantiation fails, the worker falls back to the JavaScript solver automatically. Solutions are identical either way, so no server-side changes are needed. wasm-mode and worker-mode are independent:

worker-mode controls whether solving runs in a Web Worker or on the main thread.
wasm-mode controls which solver backend runs inside a healthy worker.

Set wasm-mode="disabled" to force the JavaScript solver, for example when debugging or when a strict Content Security Policy blocks WebAssembly:

<ribaunt-widget
  challenge-endpoint="/api/captcha/challenge"
  verify-endpoint="/api/captcha/verify"
  wasm-mode="disabled"
></ribaunt-widget>

In React, pass the matching wasmMode prop:

<RibauntWidget
  challengeEndpoint="/api/captcha/challenge"
  verifyEndpoint="/api/captcha/verify"
  wasmMode="disabled"
/>

To observe which backend the worker selected, listen for the solver-backend event. The event detail reports wasm, js, or argon2id and never includes challenge contents.

wasm-mode only controls the SHA-256 solver. When your server issues Argon2id challenges, the widget detects the algorithm from the tokens, loads the Argon2id solver automatically, and reports argon2id as the backend. No widget configuration is needed to support Argon2id.

Strict CSP deployments may need wasm-unsafe-eval in script-src for WebAssembly compilation, plus access to the .wasm asset. The binary is loaded relative to the module URL, which Vite, Next.js, and native ESM resolve automatically. If your CSP blocks it, the widget still works through the JavaScript fallback.

Disabled state behavior

When you set disabled (or any value other than "false"), the widget enters a fully inert state. Specifically, it:

Blocks click interaction
Blocks keyboard activation
Makes startVerification() a no-op
Prevents auto-verify from starting
Removes the widget from the tab order
Sets aria-disabled="true" for accessibility

Use disabled to prevent users from re-submitting while your server processes a form, then clear it once the response arrives. Here is a React example that toggles the disabled prop based on a loading flag:

<RibauntWidget
  disabled={isProcessing}
  challengeEndpoint="/api/captcha/challenge"
  verifyEndpoint="/api/captcha/verify"
/>

Secondary loader (hide the percentage)

By default, the widget shows a conic progress ring with a live percentage (for example, Solving... 42%). Set show-progress="false" to switch to a quieter loader: a 12-bar pulse spinner inside the checkbox with a static Loading... label during fetching, solving, and verifying. Use this mode when you want a calmer UI, or when a moving percentage is a distraction next to the rest of your form. The default loader is unchanged, so this is fully opt-in and backwards compatible.

<ribaunt-widget
  challenge-endpoint="/api/captcha/challenge"
  verify-endpoint="/api/captcha/verify"
  show-progress="false"
></ribaunt-widget>

In React, pass the matching showProgress prop. The wrapper forwards false (or "false") through to the element verbatim, so the bars loader works the same from React. Omit the prop entirely to keep the default progress ring:

<RibauntWidget
  challengeEndpoint="/api/captcha/challenge"
  verifyEndpoint="/api/captcha/verify"
  showProgress={false}
/>

The spinner bars are drawn with currentColor, so they inherit the same color as the Loading... label across light and dark themes. Progress is still tracked internally and reported in state-change and verify event details, so telemetry and analytics keep working without changes.

Imperative methods (via ref)

You can call methods directly on the widget element to control it programmatically. In React, obtain a typed ref using RibauntWidgetHandle:

Method	Description
`startVerification()`	Programmatically start the solving flow
`reset()`	Reset widget to initial state
`getState()`	Returns current widget state string

import { useRef } from 'react';
import RibauntWidget, { type RibauntWidgetHandle } from 'ribaunt/widget-react';

const ref = useRef<RibauntWidgetHandle>(null);
// ...
ref.current?.startVerification();
ref.current?.reset();
const state = ref.current?.getState();

React-only props

In addition to the attributes above, the React wrapper accepts typed callback props and a ref. These have no HTML attribute equivalent and are handled entirely inside the React wrapper:

onVerify — fired when verification succeeds
onError — fired when an error occurs
onStateChange — fired when the widget transitions between states
onReady — fired once after the widget mounts
onLoad — alias for onReady, provided for backward compatibility
onEvent — catch-all handler for all event types
ref — imperative handle exposing reset(), getState(), and startVerification()

See the Events reference for full detail on each callback, their payload types, and usage examples.

Browser solving requires HTTPS or http://localhost. Loading from a plain LAN URL (e.g., http://192.168.x.x) will fail because the Web Crypto API is unavailable.

Get Started

Core Concepts

Server Setup

Frontend Integration

Widget

Guides

Quick example

Attribute & prop reference

Challenge endpoint response format

Adaptive difficulty (calibration)

Verification request body

WASM solver

Disabled state behavior

Secondary loader (hide the percentage)

Imperative methods (via ref)

React-only props

​Quick example

​Attribute & prop reference

​Challenge endpoint response format

​Adaptive difficulty (calibration)

​Verification request body

​WASM solver

​Disabled state behavior

​Secondary loader (hide the percentage)

​Imperative methods (via ref)

​React-only props

Quick example

Attribute & prop reference

Challenge endpoint response format

Adaptive difficulty (calibration)

Verification request body

WASM solver

Disabled state behavior

Secondary loader (hide the percentage)

Imperative methods (via ref)

React-only props