Widget API

Query Params

Parameter	Value	Description
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.
render	explicit \| 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:

Attribute	Value	Description
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-mode	inline \| popup \| hidden	(Optional) The mode the widget should be displayed in. Defaults to inline.
data-theme	light \| 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:

Error	Description
internal-error	The widget has encountered an internal error.
load-challenge-error	The challenge could not be loaded.
verify-challenge-error	The verification could not be performed.
load-audio-error	The audio challenge could not be loaded correctly.
load-slide-error	The slide challenge could not be loaded correctly.
network-error	A network error has occurred.
challenge-aborted	The challenge has been aborted by the user, e.g. by closing the modal. (Only relevant for `hidden` mode)
rate-limited	The 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.

Parameter	Value	Description
containerElement	HTMLElement \| string	The HTML Element the Widget should be rendered into.
options	<object>	An object of configuration parameters. See Options

Options

Attribute	Value	Description
sitekey	<your sitekey>	Required. Your CaptchaFox sitekey.
lang	<language code>	(Optional) Forces a specific localization. By default, CaptchaFox auto-detects the user's locale.
mode	inline \| popup \| hidden	(Optional) The mode the widget should be displayed in. Defaults to inline.
theme	light \| 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.

Parameter	Value	Description
widgetId	number	(Optional) Unique ID for a widget. Defaults to the first rendered widget.

captchafox.remove(widgetId)

Removes a specific CaptchaFox widget from the DOM.

Parameter	Value	Description
widgetId	number	(Optional) Unique ID for a widget. Defaults to the first rendered widget.

captchafox.getResponse(widgetId)

Gets the response for a specific CaptchaFox widget.

Parameter	Value	Description
widgetId	number	(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.

Parameter	Value	Description
widgetId	number	(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);
}

Theming Language Codes