vanilla-hcaptcha
Advanced tools
A Vanilla Web Component wrapper for hCaptcha. It allows for easy integration with hCaptcha in many modern web frameworks.
0 dependencies. <1kb gzipped. Integrates well with Vue.JS, React, Preact, Angular, etc.
Install | Usage | Attributes | Events | Methods
Use your favorite package manager:
yarn add vanilla-hcaptcha
npm install vanilla-hcaptcha
Or via cdn:
<script src="https://cdn.jsdelivr.net/npm/vanilla-hcaptcha"></script>
Being a vanilla web component, it is relatively easy to integrate in mainstream web frameworks such as: React, Preact, Vue.js, Angular, Stencil.js, etc. See below some examples.
<root>/examples/cdn directory.Example: display invisible hCaptcha and render programmatically.
Import once in application (main.js). Ignore the custom element.
import "vanilla-hcaptcha";
Vue.config.ignoredElements = [
"h-captcha"
];
Add handling methods
methods: {
onError(e) {
console.log('hCaptcha error: ', e);
},
onCaptchaVerified(e) {
console.log("Captcha is verified", { token: e.token, eKey: e.eKey });
}
}
Integrate in your vue component
<template>
...
<h-captcha site-key="781559eb-513a-4bae-8d29-d4af340e3624"
size="invisible"
@error="onError"
@verified="onCaptchaVerified"></h-captcha>
...
</template>
Example: display normal size hCaptcha with dark theme.
Import once in application (index.js).
import 'vanilla-hcaptcha';
Add event handler after mount
componentDidMount() {
const signupCaptcha = document.getElementById('signupCaptcha');
signupCaptcha.addEventListener('verified', (e) => {
console.log('verified event', { token: e.token });
});
}
Integrate in your html template
<h-captcha id="signupCaptcha"
site-key="781559eb-513a-4bae-8d29-d4af340e3624"
size="normal"
theme="dark"></h-captcha>
Example: display default hCaptcha.
Import once in application (main.ts).
import 'vanilla-hcaptcha';
Add CUSTOM_ELEMENTS_SCHEMA to @NgModule.schemas
Integrate in your html template
<h-captcha [attr.site-key]="siteKey"
(verified)="onCaptchaVerified($event)"></h-captcha>
Example: display compact hCaptcha with dark theme.
<!doctype html>
<html ng-app="angularjsApp">
<head>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.8.2/angular.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/vanilla-hcaptcha"></script>
<script>
angular.module('angularjsApp', [])
.controller('ExampleController', function () {
this.siteKey = "781559eb-513a-4bae-8d29-d4af340e3624";
this.onCaptchaVerified = function (e) {
console.log('verified event', {token: e.token});
};
this.onCaptchaError = function (e) {
console.log('error event', {error: e.error});
};
});
</script>
</head>
<body>
<div ng-controller="ExampleController as ctrl">
<h-captcha site-key="{{ctrl.siteKey}}"
size="compact"
theme="dark"
ng-on-verified="ctrl.onCaptchaVerified($event)"
ng-on-error="ctrl.onCaptchaError($event)"
></h-captcha>
</div>
</body>
</html>
Example: display normal size hCaptcha accessible by keyboard (see tabindex).
<script src="https://cdn.jsdelivr.net/npm/vanilla-hcaptcha"></script>
<h-captcha id="signupCaptcha"
site-key="781559eb-513a-4bae-8d29-d4af340e3624"
size="normal"
tabindex="0"></h-captcha>
<script>
const signupCaptcha = document.getElementById('signupCaptcha');
signupCaptcha.addEventListener('verified', (e) => {
console.log('verified event', {token: e.token});
});
signupCaptcha.addEventListener('error', (e) => {
console.log('error event', {error: e.error});
});
</script>
The web component allows specifying attributes. These are split into two categories: render and api attributes.
Conveniently you can set the render properties as attributes to the web component.
If you would like to programmatically call the render() method, you can set auto-render="false" property.
| Attribute | Values/Type | Default | Description |
|---|---|---|---|
auto-render | Boolean | true | When "false" it prevents automatic rendering of the checkbox. |
sitekey (required) | String | - | Your sitekey. Please visit hCaptcha and sign up to get a sitekey. |
size | String (normal, compact, invisible) | normal | This specifies the "size" of the checkbox. hCaptcha allows you to decide how big the component will appear on render. Defaults to normal. |
theme | String (light, dark) | light | hCaptcha supports both a light and dark theme. If no theme is set, the API will default to light. |
tabindex | Integer | 0 | Set the tabindex of the widget and popup. When appropriate, this can make navigation of your site more intuitive. |
hl | String (ISO 639-2 code) | - | hCaptcha auto-detects language via the user's browser. This overrides that to set a default UI language. |
challenge-container | String | - | A custom element ID to render the hCaptcha challenge. |
rqdata | String | - | See Enterprise docs. |
These attributes are optional.
| Attribute | Values/Type | Default | Description |
|---|---|---|---|
reCaptchaCompat | Boolean | true | Disable drop-in replacement for reCAPTCHA with false to prevent hCaptcha from injecting into window.grecaptcha. |
hl | String (ISO 639-2 code) | - | hCaptcha auto-detects language via the user's browser. This overrides that to set a default UI language. |
jsapi | String | - | See Enterprise docs. |
endpoint | String | - | See Enterprise docs. |
reportapi | String | - | See Enterprise docs. |
assethost | String | - | See Enterprise docs. |
imghost | String | - | See Enterprise docs. |
sentry | Boolean | - | See Enterprise docs. |
Depending on the use case, you can or not listen to the following events.
| Event | Params | Description |
|---|---|---|
error | err | When an error occurs. Component will reset immediately after an error. |
verified | token, eKey | When challenge is completed. The token and the eKey are passed along. |
expired | - | When the current token expires. |
challenge-expired | - | When the unfinished challenge expires. |
opened | - | When the challenge is opened. |
closed | - | When the challenge is closed. |
The following methods allow for programmatic control, necessary only in case of a custom hCaptcha verification flow.
| Method | Description |
|---|---|
render(config) | Renders the checkbox. Must pass the full render config, no attributes are injected. |
execute() | Triggers a verification request. |
executeAsync() | Triggers a verification request and receive a Promise which resolved with the token results or throws in case of errors. |
reset() | Resets the hCaptcha which requires user to fill captcha again. |
yarn build
Build a production version of the component.
yarn dev
Build dev version with hot reload.
yarn test
Runs unit tests.
FAQs
Vanilla Web Component for hCaptcha. 0 dependencies. <1kb gzipped.
We found that vanilla-hcaptcha demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.