Widget

This reference documents all important public classes, properties, and methods, as well as the available HTML attributes (data-*) and events of the restcaptcha.js library.

Overview¶

The RESTCaptcha JavaScript library provides the code required for client-side integration of RESTCaptcha into your own websites.

It comes in two variants:

restcaptcha.js: The original, readable version.
restcaptcha.min.js: A minified version with all unnecessary characters removed to reduce file size and improve browser load times.

The library consists of two main components:

HeadlessRestCaptcha: A pure JavaScript client without a user interface (headless). It communicates directly with the RESTCaptcha API, solves the cryptographic challenge, and returns the result via events or callbacks. This variant is suitable for integrating with your own UIs or framework solutions.
RestCaptcha: A visual widget built on top of the headless client that automatically renders a simple user interface in the browser. It can be freely configured via HTML attributes, and supports multiple languages and modes (interactive, automatic, or invisible).

HeadlessRestCaptcha¶

A UI-less client that communicates directly with the RESTCaptcha API, solves a proof-of-work, and is driven via events (callbacks).

Constructor¶

new HeadlessRestCaptcha(apiBaseUrl, siteKey, language)

Parameters:

apiBaseUrl: Base URL of the RESTCaptcha backend (required)
siteKey: The RESTCaptcha site key (required)
language: Language code (e.g. "en"). Auto-detected if empty.

Properties¶

HeadlessRestCaptcha.language: Effective language code.

Events¶

HeadlessRestCaptcha.onStarted: Function invoked when solving starts.
HeadlessRestCaptcha.onSolved: Function invoked when the CAPTCHA has been solved successfully.
HeadlessRestCaptcha.onFailed: Function invoked on failures (e.g. invalid token, too many attempts).
HeadlessRestCaptcha.onError: Function invoked on unexpected errors.
HeadlessRestCaptcha.onReset: Function invoked after a reset.

Methods¶

HeadlessRestCaptcha.solve(): Starts backend communication, retrieves a challenge, solves the proof-of-work (SHA-256/384/512), and on success calls onSolved(token, solution).
HeadlessRestCaptcha.reset(token): Invalidates a previously obtained token.
HeadlessRestCaptcha.isHeadless(): Checks whether the calling browser is most likely headless or automated.

RestCaptcha¶

The visible CAPTCHA widget that automatically renders HTML and interacts with the integrated headless client.

Constructor¶

new RestCaptcha(widgetId = "restcaptcha-widget")

Parameter:

widgetId: The ID of the widget in the browser DOM (required)

RestCaptchaProblemDetails¶

Implements the RFC 9457 Problem Details standard for structured API errors. Extends JavaScript’s Error class.

Constructor¶

new RestCaptchaProblemDetails({
  type = 'about:blank',
  title = 'Unknown error',
  status = 0,
  detail = null,
  instance = null,
  traceId = null,
  errors = null
} = {})

The parameter is an anonymous object with the corresponding properties (see the next section, “Properties”).

Properties¶

RestCaptchaProblemDetails.type: URI describing the error type.
RestCaptchaProblemDetails.title: Short, human-readable summary.
RestCaptchaProblemDetails.status: HTTP status code.
RestCaptchaProblemDetails.detail: Detailed error description.
RestCaptchaProblemDetails.instance: URI identifying this error occurrence.
RestCaptchaProblemDetails.traceId: Server-side diagnostic ID.
RestCaptchaProblemDetails.errors: Field-level validation errors (optional).

Instance methods¶

RestCaptchaProblemDetails.toString(): Returns the error as [Status] Title: Detail.

Static methods¶

RestCaptchaProblemDetails.fromResponse(response, json): Creates a RestCaptchaProblemDetails instance from a fetch() response and its JSON body.

Widget `data-*` attributes¶

These HTML attributes control the widget’s behaviour and appearance.

Basic configuration¶

data-api-baseurl: Base URL of the RESTCaptcha API (required)
data-sitekey: Public site key (required)
data-widget-language: Language code (de, en, es, fr, it, pt). By default, the script attempts to detect the language from the browser, falling back to en.
data-widget-mode: Mode. Possible values are interactive (default), auto, or invisible.

Callback attributes¶

data-callback-started > () => void: Callback after the challenge has started on the client.
data-callback-solved > (token, solution) => void: Callback after a successful verification has been reported.
data-callback-failed > (message) => void: Callback after an invalid verification has been reported.
data-callback-error > (error) => void: Callback after an API error has been reported.
data-callback-reset > (token) => void: Callback after the reset link has been clicked.

Example:

<script>
  function onCaptchaSolved(token, solution) {
    console.log("Solved:", token, solution);
  }
</script>

<div id="restcaptcha-widget"
     data-api-baseurl="https://captcha.example.com/v1/"
     data-sitekey="<My-Site-Key>"
     data-widget-language="en"
     data-callback-solved="onCaptchaSolved">
</div>

CSS class attributes¶

The widget allows full control over CSS classes via data-widget-css-* attributes.

Some attributes are specific to certain visual states (e.g. data-widget-css-interactive), while others are used across all states (e.g. data-widget-css-footer). In combination with the HTML nodes’ id values, this provides maximum flexibility.

Example for Bootstrap 5:

<div 
  id="restcaptcha-widget" 
  data-api-baseurl="https://captcha.example.com/v1/"
  data-sitekey="<My-Site-Key>"
  data-widget-language="en"
  data-widget-mode="interactive" 
  data-widget-css-interactive="alert alert-light"
  data-widget-css-interactive-body="form-check"
  data-widget-css-interactive-checkbox="form-check-input"
  data-widget-css-interactive-checklabel="form-check-label"
  data-widget-css-solving="alert alert-light"
  data-widget-css-solving-body="d-flex align-items-center"
  data-widget-css-solving-animation="spinner-border spinner-border-sm me-3"
  data-widget-css-solved="alert alert-success"
  data-widget-css-solved-body="d-flex align-items-center"
  data-widget-css-solved-icon="me-2"
  data-widget-css-solved-text="fw-bold"
  data-widget-css-failed="alert alert-warning"
  data-widget-css-failed-body="d-flex align-items-center"
  data-widget-css-failed-icon="me-2"
  data-widget-css-error="alert alert-danger"
  data-widget-css-error-body="d-flex align-items-center"
  data-widget-css-error-icon="me-2"
  data-widget-css-footer="d-flex justify-content-end align-items-center mt-3 mb-1 gap-2"
  data-widget-css-links="d-flex gap-2"
  data-widget-css-link-external="link-secondary link-offset-1"
  data-widget-css-link-reset="link-offset-1"
>
</div>

Below are all five possible RESTCaptcha visual states in abstract form.

UI for the interactive mode:

<div id="${widgetId}-interactive" class="${data-widget-css-interactive}" role="alert">
    <div id="${widgetId}-interactive-body" class="${data-widget-css-interactiveBody}">
        <input id="${widgetId}-interactive-checkbox" type="checkbox" class="${data-widget-css-interactiveCheckBox}">
        <label id="${widgetId}-interactive-checklabel" for="${widgetId}-interactive-checkbox" class="${data-widget-css-interactiveCheckLabel}">
            // Text
        </label>
    </div>  
    <div id="${widgetId}-footer" class="${data-widget-css-footer}">
        <div id="${widgetId}-logo" class="${data-widget-css-logo}" role="img" aria-hidden="true">
            // RESTCaptcha Logo
        </div>
        <small id="${widgetId}-links" class="${data-widget-css-links}">
            // External Links
        </small>
    </div>
</div>

UI for the solving state:

<div id="${widgetId}-solving" class="${data-widget-css-solving}" role="alert">
    <div id="${widgetId}-solving-body" class="${data-widget-css-solvingBody}">
        <div id="${widgetId}-solving-animation" class="${data-widget-css-solvingAnimation}" role="status" aria-hidden="true"></div>
        <div id="${widgetId}-solving-text" class="${data-widget-css-solvingText}">
            // Text
        </div>
    </div>
    <div id="${widgetId}-footer" class="${data-widget-css-footer}">
        <div id="${widgetId}-logo" class="${data-widget-css-logo}" role="img" aria-hidden="true">
            // RESTCaptcha Logo
        </div>
        <small id="${widgetId}-links" class="${data-widget-css-links}">
            // External Links
        </small>
    </div>
</div>

UI for a successfully validated challenge:

<div id="${widgetId}-success" class="${data-widget-css-solved}" role="alert">
    <div id="${widgetId}-success-body" class="${data-widget-css-solvedBody}">
        <div id="${widgetId}-success-icon" class="${data-widget-css-solvedIcon}">
            // Icon
        </div>
        <div id="${widgetId}-success-text" class="${data-widget-css-solvedText}">
            // Text
        </div>
    </div>
    <div id="${widgetId}-footer" class="${data-widget-css-footer}">
        <div id="${widgetId}-logo" class="${data-widget-css-logo}" role="img" aria-hidden="true">
            // RESTCaptcha Logo
        </div>
        <small id="${widgetId}-links" class="${data-widget-css-links}">
            // External Links
        </small>
    </div>
</div>

UI for a failed challenge:

<div id="${widgetId}-failed" class="${data-widget-css-failed}" role="alert">
    <div id="${widgetId}-failed-body" class="${data-widget-css-failedBody}">
        <div id="${widgetId}-failed-icon" class="${data-widget-css-failedIcon}">
            // Icon
        </div>
        <div id="${widgetId}-failed-text" class="${data-widget-css-failedText}">
            // Error message
        </div>
    </div>
    <div id="${widgetId}-footer" class="${data-widget-css-footer}">
        <div id="${widgetId}-logo" class="${data-widget-css-logo}" role="img" aria-hidden="true">
            // RESTCaptcha Logo
        </div>
        <small id="${widgetId}-links" class="${data-widget-css-links}">
            // External Links
        </small>
    </div>
</div>

UI for API errors:

<div id="${widgetId}-error" class="${data-widget-css-error}" role="alert">
    <div id="${widgetId}-error-body" class="${data-widget-css-errorBody}">
        <div id="${widgetId}-error-icon" class="${data-widget-css-errorIcon}">
            // Icon
        </div>
        <div id="restcaptcha-error-text" class="${data-widget-css-errorText}">
            // Error message
        </div>
    </div>
    <div id="${widgetId}-footer" class="${data-widget-css-footer}">
        <div id="${widgetId}-logo" class="${data-widget-css-logo}" role="img" aria-hidden="true">
            // RESTCaptcha Logo
        </div>
        <small id="${widgetId}-links" class="${data-widget-css-links}">
            // External Links
        </small>
    </div>
</div>

External links¶

You can display up to eight additional links, e.g. to privacy or legal information.

Example:

<div id="restcaptcha-widget"
  data-widget-external-link1-href="https://www.example.com/restcaptcha"
  data-widget-external-link1-text="About RESTCaptcha"
  data-widget-external-link2-href="https://www.example.com/privacy"
  data-widget-external-link2-text="Privacy">
</div>

Events & callbacks¶

There are two approaches to handling events: programmatic (headless) or declarative (via HTML attributes).

Programmatic:

const h = new HeadlessRestCaptcha(api, siteKey, 'de');

h.onStarted = () => console.log("Started");
h.onSolved = (token, solution) => console.log("Solved:", token, solution);
h.onFailed = msg => alert(msg);
h.onError = e => console.error(e);
h.onReset = () => console.log("Reset");

h.solve();

Declarative:

<script>
  function captchaStarted() { console.log("Started"); }
  function captchaSolved(token, solution) { console.log("Solved:", token, solution); }
  function captchaFailed(msg) { alert(msg); }
</script>

<div id="restcaptcha-widget"
  data-api-baseurl="https://captcha.example.com/v1/"
  data-sitekey="<My-Site-Key>"
  data-callback-started="captchaStarted"
  data-callback-solved="captchaSolved"
  data-callback-failed="captchaFailed">
  ...
</div>

Automatic initialisation¶

On document load (DOMContentLoaded), the script automatically looks for an element with the ID restcaptcha-widget and initialises it with:

new RestCaptcha("restcaptcha-widget");

If the element is missing, nothing further happens.

Widget

Overview¶

HeadlessRestCaptcha¶

Constructor¶

Properties¶

Events¶

Methods¶

RestCaptcha¶

Constructor¶

RestCaptchaProblemDetails¶

Constructor¶

Properties¶

Instance methods¶

Static methods¶

Widget data-* attributes¶

Basic configuration¶

Callback attributes¶

CSS class attributes¶

External links¶

Events & callbacks¶

Automatic initialisation¶

Widget `data-*` attributes¶