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 if 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.
npm install @hcaptcha/loader
Or use UNPKG to load via CDN, as described below.
import { hCaptchaLoader } from '@hcaptcha/loader';
await hCaptchaLoader();
hcaptcha.render({
sitekey: '<your_sitekey>'
});
const { response } = await hcaptcha.execute({ async: true });| Name | Values/Type | Required | Default | Description |
|---|---|---|---|---|
loadAsync |
Boolean | No | true |
Set if the script should be loaded asynchronously. |
cleanup |
Boolean | No | true |
Remove script tag after setup. |
crossOrigin |
String | No | - |
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. |
custom |
Boolean | No | - |
See enterprise docs. |
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.
Both bundles generated use IIFE format rather than a more modern import syntax such as require or esm.
// 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
});
});To handle typescript with ES5 version, use the following statement.
declare global {
interface Window {
hCaptchaLoader: any;
}
}The hCaptcha Loader targeted for older browsers can also be imported via CDN by using UNPKG, see example below.
<!DOCTYPE html>
<head>
<script type="text/javascript" src="https://unpkg.com/@hcaptcha/loader@latest/dist/polyfills.js"></script>
<script type="text/javascript" src="https://unpkg.com/@hcaptcha/loader@latest/dist/index.es5.js"></script>
</head>
<body>
<div id="container"></div>
<script type="text/javascript">
hCaptchaLoader().then(function(hcaptcha) {
// hCaptcha API is ready
hcaptcha.render('container', {
sitekey: 'YOUR_SITE_KEY',
// Additional options here
});
});
</script>
</body>
</html>Note that you should use the strict-dynamic policy for this loader, as it needs to load the SDK via appendChild().