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"
  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 solving. Omit to leave solving un-timed.
`worker-mode`	`workerMode`	`‘preferred'	'required'	'disabled’`	`'preferred'`	Controls whether the widget uses a Web Worker for solving.
`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"`.
`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" }]
}

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"
/>

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

Disabled state behavior

Imperative methods (via ref)

React-only props

​Quick example

​Attribute & prop reference

​Challenge endpoint response format

​Adaptive difficulty (calibration)

​Verification request body

​Disabled state behavior

​Imperative methods (via ref)

​React-only props

Quick example

Attribute & prop reference

Challenge endpoint response format

Adaptive difficulty (calibration)

Verification request body

Disabled state behavior

Imperative methods (via ref)

React-only props