hCaptcha Loader

This is a JavaScript library to easily configure the loading of the hCaptcha JS client SDK with built-in error handling. It also includes a retry mechanism that will attempt to load the hCaptcha script several times in the event it fails to load due to a network or unforeseen issue.

> hCaptcha is a drop-replacement for reCAPTCHA that protects user privacy.
>
> Sign up at hCaptcha to get your sitekey today. You need a sitekey to use this library.

- hCaptcha Loader
- Installation
- Implementation
- Props
- Legacy Support
- Import Bundle(s)
- TypeScript
- CDN
- CSP
- Sentry

Installation

``
npm install @hcaptcha/loader
`

Or use UNPKG to load via CDN, as described below.

Implementation

`js
import { hCaptchaLoader } from '@hcaptcha/loader';

await hCaptchaLoader();

hcaptcha.render({
sitekey: ''
});

const { response } = await hcaptcha.execute({ async: true });
`

Props


| Name | Values/Type | Required | Default | Description |
|-------------------|-------------|----------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| loadAsync | Boolean | No | true | Set if the script should be loaded asynchronously. |
| cleanup | Boolean | No | false | Remove script tag after setup. |
| crossOrigin | String | No | anonymous | Set script cross origin attribute such as "anonymous". |
| scriptSource | String | No | https://js.hcaptcha.com/1/api.js | Set script source URI. Takes precedence over secureApi. |
| scriptLocation | HTMLElement | No | document.head | Location of where to append the script tag. Make sure to add it to an area that will persist to prevent loading multiple times in the same document view. |
| secureApi | Boolean | No | false | See enterprise docs. |
| apihost | String | No | - | See enterprise docs. |
| assethost | String | No | - | See enterprise docs. |
| endpoint | String | No | - | See enterprise docs. |
| hl | String | No | - | See enterprise docs. |
| host | String | No | - | See enterprise docs. |
| imghost | String | No | - | See enterprise docs. |
| recaptchacompat | String | No | - | See enterprise docs. |
| reportapi | String | No | - | See enterprise docs. |
| sentry | Boolean | No | - | See enterprise docs. |
| uj | Boolean | No | - | See enterprise docs. |
| custom | Boolean | No | - | See enterprise docs. |

Legacy Support

In order to support older browsers, a separate bundle is generated in which all ES6 code is compiled down to ES5 along with an optional polyfill bundle.

- polyfills.js: Provides polyfills for features not supported in older browsers.
- index.es5.js: @hcaptcha/loader package compiled for ES5 environments.

$3


Both bundles generated use IIFE format rather than a more modern import syntax such as require or esm.

`js
// Optional polyfill import
import '@hCaptcha/loader/dist/polyfills.js';
// ES5 version of hCaptcha Loader
import '@hCaptcha/loader/dist/index.es5.js';

hCaptchaLoader().then(function(hcaptcha) {
var element = document.createElement('div');
// hCaptcha API is ready
hcaptcha.render(element, {
sitekey: 'YOUR_SITE_KEY',
// Additional options here
});
});

`


$3


To handle typescript with ES5 version, use the following statement.
`ts
declare global {
interface Window {
hCaptchaLoader: any;
}
}
`

$3

The hCaptcha Loader targeted for older browsers can also be imported via CDN by using UNPKG, see example below.


`html












`

CSP

Note that you should use the strict-dynamic policy for this loader, as it needs to load the SDK via appendChild().

Sentry

You can disable Sentry error tracking by setting the sentry flag to false, which will prevent client-side error reports from being sent to us.

`js
hCaptchaLoader({ sentry: false });
``