> ## Documentation Index
> Fetch the complete documentation index at: https://captcha.ribaunt.com/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, challenge method, calibration, and challenge response formats.

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:

```html theme={null}
<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[] }`.

<Info>
  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.
</Info>

## 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}
<ribaunt-widget
  challenge-endpoint="/api/captcha/challenge"
  verify-endpoint="/api/captcha/verify"
  challenge-method="POST"
  calibrate="true"
  auto-verify="true"
></ribaunt-widget>
```

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" }]
}
```

## 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}
<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     |

```tsx theme={null}
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](/widget/events) for full detail on each callback, their payload types, and usage examples.

<Note>
  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.
</Note>