⚠️This project was moved to @hcaptcha/vanilla-hcaptcha.⚠️
---

hCaptcha - Vanilla Web Component

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

Install

Use your favorite package manager:
``bash
yarn add vanilla-hcaptcha
`

`bash
npm install vanilla-hcaptcha
`

Or via cdn:
`html

`

Usage

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 /examples/cdn directory.

$3

> 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

`

$3

> 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
site-key="781559eb-513a-4bae-8d29-d4af340e3624"
size="normal"
theme="dark">
`

$3

> Example: display default hCaptcha.

1. Import once in application (main.ts).
`js
import 'vanilla-hcaptcha';
`
2. Add CUSTOM_ELEMENTS_SCHEMA to @NgModule.schemas

3. Integrate in your html template
`html
(verified)="onCaptchaVerified($event)">

`

$3

> 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`
> Runs unit tests.