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
| Browser Compatibility
| Usage
| Form Integration
| Attributes
| Events
| Methods

Install

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

`bash
pnpm add @hcaptcha/vanilla-hcaptcha
`

`bash
npm install @hcaptcha/vanilla-hcaptcha
`

Or via cdn:
`html

`

Browser Compatibility

hCaptcha web component is using es6 syntax and window property customElements.

| Browser | Min Version |
|-----------------|-------------|
| Chrome | 54 |
| Edge | 79 |
| Firefox | 63 |
| Opera | 41 |
| Safari | 10.1 |
| Chrome Android | 54 |
| Firefox Android | 63 |

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
* Next.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 "@hcaptcha/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 '@hcaptcha/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 '@hcaptcha/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 with dark theme.

1. Add h-captcha web component type by extending JSX.IntrinsicElements in *.d.ts.
`ts
import * as React from 'react';

declare global {
declare namespace JSX {
interface IntrinsicElements {
'h-captcha': React.DetailedHTMLProps & {
[k: string]: unknown;
}, HTMLElement>;
}
}
}
`

2. Integrate in your next.js page.
`js
export default function HomeComponent() {
const sitekey = '781559eb-513a-4bae-8d29-d4af340e3624';
const captchaRef = createRef();

useEffect(() => {
import('@hcaptcha/vanilla-hcaptcha');

if (captchaRef.current) {
captchaRef.current.addEventListener('verified', (e: Event) => {
console.log('hCaptcha event: verified', { token: e.token });
});
}
}, []);

return (



ref={captchaRef}
sitekey={sitekey}
size="normal"
theme="dark"
>



);
}
`

$3

> Example: display normal size hCaptcha accessible by keyboard (see tabindex).

`html


site-key="781559eb-513a-4bae-8d29-d4af340e3624"
size="normal"
tabindex="0">


`

Form Integration

When using hCaptcha within forms, you must manually control the verification flow to ensure proper security. The hCaptcha component should be triggered on form submission, and the actual form submission should only happen after successful verification.

$3

1. Prevent default form submission - Use preventDefault() to stop immediate form submission
2. Execute hCaptcha verification - Call .execute() method to trigger the challenge
3. Handle verification result - Submit the form only when the verified event fires

$3

`html


Submit

site-key="your-site-key"
size="invisible">


`

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-1 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-1 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 |
|----------------------|----------------|---------------------------------------------------------------------------|
| loaded | - | When the hCaptcha loaded and is ready for challenge execution. Usually used in combination with size=invisible or when manual .execute() is required. |
| 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

* pnpm build
> Build a production version of the component.

* pnpm dev
> Build dev version with hot reload.

* pnpm test`
> Runs unit tests.