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>

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