Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hcaptcha/vanilla-hcaptcha
A Vanilla Web Component wrapper for hCaptcha. Allows for easy integration with hCaptcha in many modern web frameworks.
https://github.com/hcaptcha/vanilla-hcaptcha
angular angular2 angular3 angularjs preact preactjs react reactjs vue vue3 vuejs
Last synced: 3 days ago
JSON representation
A Vanilla Web Component wrapper for hCaptcha. Allows for easy integration with hCaptcha in many modern web frameworks.
- Host: GitHub
- URL: https://github.com/hcaptcha/vanilla-hcaptcha
- Owner: hCaptcha
- License: mit
- Created: 2024-04-11T10:08:06.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2024-04-22T09:57:26.000Z (5 months ago)
- Last Synced: 2024-09-21T06:04:11.641Z (7 days ago)
- Topics: angular, angular2, angular3, angularjs, preact, preactjs, react, reactjs, vue, vue3, vuejs
- Language: TypeScript
- Homepage:
- Size: 479 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
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});
};
});
```
### 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
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});
});
```
## 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-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. |
### 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-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
* `pnpm build`
> Build a production version of the component.
* `pnpm dev`
> Build dev version with hot reload.
* `pnpm test`
> Runs unit tests.