# hCaptcha - Vanilla Web Component A Vanilla Web Component wrapper for [hCaptcha](https://docs.hcaptcha.com/). 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](#install) | [Browser Compatibility](#browser-compatibility) | [Usage](#usage) | [Attributes](#attributes) | [Events](#events) | [Methods](#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](https://developer.mozilla.org/en-US/docs/Web/API/Window/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](https://custom-elements-everywhere.com) to integrate in mainstream web frameworks such as: React, Preact, Vue.js, Angular, Stencil.js, etc. See below some examples. * [Vue.JS](#vuejs) * [React](#reactjs-and-preact) * [Preact](#reactjs-and-preact) * [Angular 2+](#angular) * [Angular.JS](#angularjs) * [Next.JS](#nextjs) * [Vanilla](#vanillajs) * You can find more examples in the `/examples/cdn` directory. ### Vue.JS > 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 ``` ### React.JS and Preact > 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 ``` ### Angular > Example: display default hCaptcha. 1. Import once in application (`main.ts`). ```js import '@hcaptcha/vanilla-hcaptcha'; ``` 2. Add [`CUSTOM_ELEMENTS_SCHEMA`](https://angular.io/api/core/CUSTOM_ELEMENTS_SCHEMA) to `@NgModule.schemas` 3. Integrate in your html template ```html ``` ### Angular.JS > Example: display compact hCaptcha with dark theme. ```html

``` ### Next.JS > 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 (

); } ``` ### Vanilla.JS > Example: display normal size hCaptcha accessible by keyboard (see [tabindex](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)). ```html

``` ## Attributes The web component allows specifying attributes. These are split into two categories: render and api attributes. ### Render 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](https://www.hcaptcha.com) 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. | ### API Attributes 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 | |----------------------|----------------|---------------------------------------------------------------------------| | `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.