Widget API

Widget API

Query Params

ParameterValueDescription
onload<function name>(Optional) The name of your custom callback function to be called once the CaptchaFox API has loaded. Must be defined before the API loads.
renderexplicit | onload(Optional) Whether or not to render the widget automatically. Defaults to onload.
lang<language code>(Optional) Forces a specific localization. By default, CaptchaFox auto-detects the user's locale.

Parameters are set as key=value pairs following a ? after the script name. For instance, if you want to always render captchas in German, your script tag should look like this:

<script async defer src="https://cdn.captchafox.com/api.js?lang=de"></script>

Multiple query params are separated by &:

<script async defer src="https://cdn.captchafox.com/api.js?lang=de&render=explicit"></script>

Container Attributes

Additionally to the required data-sitekey attribute you can pass the following attributes to the container element:

AttributeValueDescription
data-sitekey<your sitekey>Required. Your CaptchaFox sitekey.
data-lang<language code>(Optional) Forces a specific localization. By default, CaptchaFox auto-detects the user's locale.
data-modeinline | popup | hidden(Optional) The mode the widget should be displayed in. Defaults to inline.
data-themelight | dark(Optional) The theme of the widget. Defaults to light.
data-callback<function name>(Optional) Called with the response token after successful verification.
data-expired-callback<function name>(Optional) Called when the response expires.
data-fail-callback<function name>(Optional) Called after unsuccessful verification
data-close-callback<function name>(Optional) Called when the challenge was closed
data-error-callback<function name>(Optional) Called when CaptchaFox encounters an error. Inform the user that they should retry.

Example:

<div
  class="captchafox"
  data-sitekey="YOUR_SITEKEY"
  data-lang="es"
  data-callback="verifyAndSubmit"
  data-error-callback="showError"
></div>

Error Codes

If the CaptchaFox widget encounters an error, an error code is sent to the error event (e.g. data-error-callback).

Below you will find a list of possible errors and their causes:

ErrorDescription
internal-errorThe widget has encountered an internal error.
load-challenge-errorThe challenge could not be loaded.
verify-challenge-errorThe verification could not be performed.
load-audio-errorThe audio challenge could not be loaded correctly.
load-slide-errorThe slide challenge could not be loaded correctly.
network-errorA network error has occurred.
rate-limitedThe user has sent too many requests.

JavaScript API

The JavaScript tag exposes the captchafox window object that provides methods to customize the CaptchaFox behavior.

captchafox.render(containerElement, options)

Renders the CaptchaFox widget inside the container element and returns a unique widgetId.

ParameterValueDescription
containerElementHTMLElement | stringThe HTML Element the Widget should be rendered into.
options<object>An object of configuration parameters. See Options
Options
AttributeValueDescription
sitekey<your sitekey>Required. Your CaptchaFox sitekey.
lang<language code>(Optional) Forces a specific localization. By default, CaptchaFox auto-detects the user's locale.
modeinline | popup | hidden(Optional) The mode the widget should be displayed in. Defaults to inline.
themelight | dark | ThemeDefinition(Optional) The theme of the widget. Defaults to light.
i18n<object>(Optional) i18n configuration. Allows overriding i18n labels for specific languages.
onVerify<function>(Optional) Called with the response token after successful verification.
onExpire<function>(Optional) Called when the response expires.
onFail<function>(Optional) Called after unsuccessful verification
onClose<function>(Optional) Called when the challenge was closed
onError<function>(Optional) Called when CaptchaFox encounters an error. Inform the user that they should retry.

captchafox.reset(widgetId)

Resets a specific CaptchaFox widget.

ParameterValueDescription
widgetIdnumber(Optional) Unique ID for a widget. Defaults to the first rendered widget.

captchafox.remove(widgetId)

Removes a specific CaptchaFox widget from the DOM.

ParameterValueDescription
widgetIdnumber(Optional) Unique ID for a widget. Defaults to the first rendered widget.

captchafox.getResponse(widgetId)

Gets the response for a specific CaptchaFox widget.

ParameterValueDescription
widgetIdnumber(Optional) Unique ID for a widget. Defaults to the first rendered widget.

captchafox.execute(widgetId)

Programattically triggers the CaptchaFox challenge flow. Used in a custom integration or when setting mode to hidden.

ParameterValueDescription
widgetIdnumber(Optional) Unique ID for a widget. Defaults to the first rendered widget.

Upon successful completion of the challenge, it will resolve with the response token. In case of an error, it will reject.

try {
  const token = await captchafox.execute(widgetId);
  console.log(token);
} catch (error) {
  console.error(error);
}