Skip to content
This repository has been archived by the owner on Apr 17, 2024. It is now read-only.
/ vanilla-hcaptcha Public archive

Vanilla Web Component for hCaptcha. 0 dependencies. <1kb gzipped. Integrates well with Vue.JS, React, Angular.

License

MIT license
16 stars 4 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

DSergiu/vanilla-hcaptcha

BranchesTags

Repository files navigation

⚠️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.

hCaptcha logo

0 dependencies. <1kb gzipped. Integrates well with Vue.JS, React, Preact, Angular, etc.

Install | Usage | Attributes | Events | Methods

Install

Use your favorite package manager:

yarn add vanilla-hcaptcha
npm install vanilla-hcaptcha

Or via cdn:

<script src="https://cdn.jsdelivr.net/npm/vanilla-hcaptcha"></script>

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

Example: display invisible hCaptcha and render programmatically.

  1. Import once in application (main.js). Ignore the custom element.

    import "vanilla-hcaptcha";

Vue.config.ignoredElements = [
  "h-captcha"
];

  2. Add handling methods

    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

    <template>
    ...
    <h-captcha site-key="781559eb-513a-4bae-8d29-d4af340e3624"
               size="invisible"
               @error="onError"
               @verified="onCaptchaVerified"></h-captcha>
    ...
</template>

React.JS and Preact

Example: display normal size hCaptcha with dark theme.

  1. Import once in application (index.js).

    import 'vanilla-hcaptcha';

  2. Add event handler after mount

    componentDidMount() {
    const signupCaptcha = document.getElementById('signupCaptcha');
    signupCaptcha.addEventListener('verified', (e) => {
      console.log('verified event', { token: e.token });
    });
}

  3. Integrate in your html template

     <h-captcha id="signupCaptcha"
            site-key="781559eb-513a-4bae-8d29-d4af340e3624"
            size="normal"
            theme="dark"></h-captcha>

Angular

Example: display default hCaptcha.

  1. Import once in application (main.ts).

    import 'vanilla-hcaptcha';

  2. Add CUSTOM_ELEMENTS_SCHEMA to @NgModule.schemas

  3. Integrate in your html template

     <h-captcha [attr.site-key]="siteKey"
            (verified)="onCaptchaVerified($event)"></h-captcha>

Angular.JS

Example: display compact hCaptcha with dark theme.

<!doctype html>
<html ng-app="angularjsApp">
<head>
    <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.8.2/angular.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/vanilla-hcaptcha"></script>

    <script>
        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});
                    };
                });
    </script>
</head>
<body>
<div ng-controller="ExampleController as ctrl">
    <h-captcha site-key="{{ctrl.siteKey}}"
               size="compact"
               theme="dark"
               ng-on-verified="ctrl.onCaptchaVerified($event)"
               ng-on-error="ctrl.onCaptchaError($event)"
    ></h-captcha>
</div>
</body>
</html>

Vanilla.JS

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

<script src="https://cdn.jsdelivr.net/npm/vanilla-hcaptcha"></script>

<h-captcha id="signupCaptcha"
           site-key="781559eb-513a-4bae-8d29-d4af340e3624"
           size="normal"
           tabindex="0"></h-captcha>

<script>
    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});
    });
</script>

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 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

  • yarn build

    Build a production version of the component.

  • yarn dev

    Build dev version with hot reload.

  • yarn test

    Runs unit tests.

About

Vanilla Web Component for hCaptcha. 0 dependencies. <1kb gzipped. Integrates well with Vue.JS, React, Angular.

Resources

Readme

License

MIT license
Activity

Stars

16 stars

Watchers

1 watching

Forks

4 forks
Report repository

Contributors 2

  •  
  •  

Languages