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.

Parameter Value Description
onload <function name> Optional. The name of your custom callback function to be called once the hCaptcha 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, which will automatically render widgets in hcaptcha div containers.
hl <language code> Optional. Forces a specific localization. By default, hCaptcha auto-detects the user's locale. See language codes.

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://hcaptcha.com/1/api.js?hl=fr" async defer></script>

Multiple query params are separated by &.

<script src="https://hcaptcha.com/1/api.js?hl=es&onload=myFunction&render=explicit" 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.

Attribute Value Description
data-sitekey <your site key> Required. Your public API site key.
data-theme light | dark Optional. Set the color theme of the widget. Defaults to light.
data-size normal | compact Optional. Set the size of the widget. Defaults to normal.
data-tabindex <integer> Optional. Set the tabindex of the widget and popup. When appropriate, can make navigation more intuitive on your site. Defaults to 0.
data-callback <function name> Optional. Called when the user submits a successful response. The h-captcha-response token is passed to your callback.
data-expired-callback <function name> Optional. Called when the captcha response expires and the user must re-verify.
data-error-callback <function name> Optional. Called when hCaptcha encounters an error and cannot continue. If you specify an error callback, you must inform the user that they should retry.

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>

All of the above attributes can also be used as param arguments when explicitly rendering with hcatpha.render() (described in the next section). In that case, the param name is as shown above, but without the data prefix. For example, the param argument for data-tabindex is just tabindex.

<script type="text/javascript">
   hcaptcha.render('captcha-1', { 'sitekey':'your_site_key', 'theme':'dark', 'error-callback':'onError' });
</script>

JavaScript API

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

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

Explicitly Render hCaptcha

In the default implementation, hCaptcha widgets will be automatically rendered and inserted into your webpage. Howevever, 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://hcaptcha.com/1/api.js?onload=yourFunction&render=explicit" 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.

hCaptcha dark theme example.

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

hCaptcha dark theme example.

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