> ## Documentation Index > Fetch the complete documentation index at: https://ribaunt-e66481b6-mintlify-4e7c3afc.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Complete reference for all ribaunt-widget HTML attributes and React props: endpoints, auto-verify, timeout, worker mode, WASM mode, calibration, and response formats. The `` 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: ```html theme={null} ``` ## 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](#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`: 1. `{ challenges: string[] }` — recommended contract 2. `{ tokens: string[] }` — compatibility support 3. 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. ```html theme={null} ``` See [createChallenge](/api/create-challenge#adaptive-workload) for the server-side options. ## Verification request body When you provide a `verify-endpoint`, the widget sends a JSON payload shaped like this: ```json theme={null} { "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: ```html theme={null} ``` In React, pass the matching `wasmMode` prop: ```tsx theme={null} ``` To observe which backend the worker selected, listen for the [`solver-backend` event](/widget/events#solver-backend). 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](/api/create-challenge#argon2id-opt-in), 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: ```tsx theme={null} ``` ## 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. ```html theme={null} ``` 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: ```tsx theme={null} ``` 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 | ```tsx theme={null} import { useRef } from 'react'; import RibauntWidget, { type RibauntWidgetHandle } from 'ribaunt/widget-react'; const ref = useRef(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](/widget/events) 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.