Vanilla Web Component for hCaptcha. 0 dependencies. <1kb gzipped.
⚠️This project was moved to @hcaptcha/vanilla-hcaptcha.⚠️
---
0 dependencies. <1kb gzipped. Integrates well with Vue.JS, React, Preact, Angular, etc.
Install | Usage | Attributes | Events | Methods
Use your favorite package manager:
``bash`
yarn add vanilla-hcaptcha
`bash`
npm install vanilla-hcaptcha
Or via cdn:
`html`
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.
* Vue.JS
* React
* Preact
* Angular 2+
* Angular.JS
* Vanilla
* You can find more examples in the directory.
> Example: display invisible hCaptcha and render programmatically.
1. Import once in application (main.js). Ignore the custom element.`
js`
import "vanilla-hcaptcha";
Vue.config.ignoredElements = [
"h-captcha"
];
`
2. Add handling methods
js`
methods: {
onError(e) {
console.log('hCaptcha error: ', e);
},
onCaptchaVerified(e) {
console.log("Captcha is verified", { token: e.token, eKey: e.eKey });
}
}
3. Integrate in your vue component
`html`
...
@error="onError"
@verified="onCaptchaVerified">
...
> Example: display normal size hCaptcha with dark theme.
1. Import once in application (index.js).`
js`
import 'vanilla-hcaptcha';
2. Add event handler after mount
`js`
componentDidMount() {
const signupCaptcha = document.getElementById('signupCaptcha');
signupCaptcha.addEventListener('verified', (e) => {
console.log('verified event', { token: e.token });
});
}
3. Integrate in your html template
`html`
size="normal"
theme="dark">
> Example: display default hCaptcha.
1. Import once in application (main.ts).`
js`
import 'vanilla-hcaptcha';
CUSTOM_ELEMENTS_SCHEMA
2. Add to @NgModule.schemas
3. Integrate in your html template
`html`
> Example: display compact hCaptcha with dark theme.
`html
$3
> Example: display normal size hCaptcha accessible by keyboard (see tabindex).
`html site-key="781559eb-513a-4bae-8d29-d4af340e3624"
size="normal"
tabindex="0">
`Attributes
The web component allows specifying attributes. These are split into two categories: render and api attributes.
$3
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. |$3
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. |
Events
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. |Methods
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. |Commands
*
yarn build
> Build a production version of the component.*
yarn dev
> Build dev version with hot reload.*
yarn test`