vanilla-hcaptcha

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #typescript #llm #go #android #rust #deep-learning #java #nodejs #vue #pytorch #open-source

vanilla-hcaptcha

(★ 20)

A Vanilla Web Component wrapper for hCaptcha. Allows for easy integration with hCaptcha in many modern web frameworks.

vanilla-hcaptcha Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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

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
<script src="https://cdn.jsdelivr.net/npm/@hcaptcha/vanilla-hcaptcha"></script>
```

## 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 `<root>/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
    <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`).
    ```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
    <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`).
    ```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
    <h-captcha [attr.site-key]="siteKey"
               (verified)="onCaptchaVerified($event)"></h-captcha>
   ```

### Angular.JS

> Example: display compact hCaptcha with dark theme.

```html
<!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/@hcaptcha/vanilla-hcaptcha"></script>

### 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<React.HTMLAttributes<HTMLElement> & {
            [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<HTMLElement>();

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

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

return (
      <main>
        <h-captcha
            ref={captchaRef}
            sitekey={sitekey}
            size="normal"
            theme="dark"
        ></h-captcha>
      </main>
      );
    }
   ```

### 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
<script src="https://cdn.jsdelivr.net/npm/@hcaptcha/vanilla-hcaptcha"></script>

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

signupCaptcha.addEventListener('verified', (e) => {
        console.log('verified event', {token: e.token});
    });
    signupCaptcha.addEventListener('error', (e) => {
        console.log('error event', {error: e.error});
    });
</script>
```

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

### Required Flow

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

### Minimalist Example

```html
<form id="myForm">
    <input type="email" name="email" placeholder="Your email" required>
    <button type="submit">Submit</button>

<h-captcha id="hcaptchaEl"
               site-key="your-site-key"
               size="invisible"></h-captcha>
</form>

// 1. Intercept form submission
form.addEventListener('submit', (e) => {
    e.preventDefault(); // Stop default submission
    hcaptchaEl.execute(); // Trigger hCaptcha verification
});

// 2. Handle successful verification
hcaptchaEl.addEventListener('verified', (e) => {
    console.log("hCaptcha successfull verification", { token: e.token })
    // Now submit the form
    form.submit();
});

// 3. Handle errors
hcaptchaEl.addEventListener('error', (e) => {
    console.error('hCaptcha error:', e.error);
    // Show user-friendly error message
});
</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](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                                                               |
|----------------------|----------------|---------------------------------------------------------------------------|
| `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.

## Deploy

Publishing to npm is handled automatically via GitHub Actions using [OIDC Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (no npm token required).

### Release Flow

1. Bump the version in `packages/vanilla-hcaptcha/package.json`.
2. Merge changes to `master`.
3. Create a [GitHub Release](https://github.com/hCaptcha/vanilla-hcaptcha/releases/new) with a tag matching the version (e.g. `v1.2.0`).
4. The `publish.yml` workflow will automatically run the full CI (build, typecheck, test) and publish to npm.

### Workflows

| Workflow | Trigger | Purpose |
|----------|---------|---------|
| `ci.yml` | Push/PR to `master` | Build, typecheck, and test |
| `publish.yml` | GitHub Release published | Full CI + publish to npm via OIDC |

vanilla-hcaptcha

vanilla-hcaptcha Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

vanilla-hcaptcha

vanilla-hcaptcha Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README