Configuration

There are two ways to configure hCaptcha. The first is to pass query parameters when loading the hCaptcha javascript resource. Using query params, you can specify a custom callback function, defer rendering, or force a specific localization.

Query params are set as key=value pairs following a ? after the script name. For example, to explicitly render captchas in French, your script tag should look like this:

<script src="https://js.hcaptcha.com/1/api.js?hl=fr" async defer></script>

Multiple query params are separated by &.

<script
  src="https://js.hcaptcha.com/1/api.js?hl=es&>"
  async
  defer
></script>

hCaptcha Container Configuration​

The second way to configure hCaptcha is to set custom attributes on the hCaptcha container <div>. You're already required to do this with data-sitekey, but there are a handful of other optional attributes that enable more customization.

Besides the required data-sitekey, you can add as many or as few configuration attributes as you want.

<div
  class="h-captcha"
  data-sitekey="your_site_key"
  data-theme="dark"
  data-error-callback="onError"
></div>

<script type="text/javascript">
  hcaptcha.render('your_div_id', // string: ID of target div to render into
  {
    sitekey: 'your_site_key',
    theme: 'dark', // (for example)
    'error-callback': 'onError', // (for example) string: name of function
  });
</script>

JavaScript API​

The hCaptcha API exposes the hcaptcha object that has methods you may find useful in customizing hCaptcha behavior.

hcaptcha.render(container, params)​

Renders the hCaptcha widget inside the container DOM element. Returns a unique widgetID for the widget.

• container The string ID of the container or the container DOM element.
• params An object containing config parameters as key=value pairs. Ex:

  {
     "theme": "dark",
     "size": "compact",
     "sitekey": "your_site_key"
  }
  

hcaptcha.reset(widgetID)​

Resets the hCaptcha widget with widgetID.

• widgetID Optional unique ID for a widget. Defaults to first widget created.

hcaptcha.getResponse(widgetID)​

Gets the response for the hCaptcha widget with widgetID.

• widgetID Optional unique ID for a widget. Defaults to first widget created.

hcaptcha.getRespKey(widgetID)​

Gets the response ID for the hCaptcha widget with widgetID.

• widgetID Optional unique ID for a widget. Defaults to first widget created.

hcaptcha.execute(widgetID)​

Triggers the hCaptcha workflow programmatically. Generally used in invisible mode where the target container is a div rather than a button.

• widgetID Optional unique ID for a widget. Defaults to first widget created.

Asynchronous mode​

Optionally, you can pass { async: true } to hcaptcha.execute() in order to get a promise back.

• Upon successful completion of the challenge, it will resolve with an object containing the token and the response key.
• In case of an error, it will reject with an appropriate error code (see section below).
• It will not inform you about expired tokens, as the promise will have already resolved with the token in this scenario.
  • To handle this case you will still need to specify the expired-callback callback.

hcaptcha.execute(widgetID, { async: true })
    .then(({ response, key }) => {
        console.log(response, key);
    })
    .catch(err => {
        console.error(err);
    });

Error Codes​

The following error codes are passed as argument to the error-callback function or as rejection data to the asynchronous execute.

Please note that asynchronous .execute() calls can reject the promise with extra error codes (e.g. challenge-closed) which are not passed to the error-callback as there are other callbacks (e.g. close-callback) defined for these scenarios.

In the table below, each error code is listed, along with details to interpret it and any action suggested.

If you are using hCaptcha in a fully programmatic pattern ("invisible" mode, i.e. no checkbox, with .execute() called by your functions and errors rendered in your code rather than relying on ours) then please ensure your code follows the expected behavior by described by the Action when interpreting an error.

• * are thrown only in case of async execute

Explicitly Render hCaptcha​

In the default implementation, hCaptcha widgets will be automatically rendered and inserted into your webpage. However, you can also defer rendering by specifying a custom onload callback function in which you render the widget yourself.

To specify a custom onload callback function, you must pass the function name as an onload query parameter in the hCaptcha javascript tag. In addition, you must set the render query parameter to explicit. Your hCaptcha script tag should look like this (replace yourFunction with the name of your function):

<script
  src="https://js.hcaptcha.com/1/api.js?>"
  async
  defer
></script>

Your custom callback function must be defined before the hCaptcha script loads. You can then call hcaptcha.render with the container ID and your site key to explicitly render the widget.

<script type="text/javascript">
  var yourFunction = function () {
    console.log('hCaptcha is ready.');
    var widgetID = hcaptcha.render('captcha-1', { sitekey: 'your_site_key' });
  };
</script>

Themes​

You can apply a dark theme to the hCaptcha widget by setting the data-theme attribute of the hCaptcha container to dark.

<div class="h-captcha" data-sitekey="your_site_key" data-theme="dark"></div>

There's also a compact option to give the widget a smaller footprint. Set the data-size attribute of the hCaptcha container to compact.

<div class="h-captcha" data-sitekey="your_site_key" data-size="compact"></div>