ng-recaptcha

What is ng-recaptcha?

The ng-recaptcha package is an Angular library that provides a simple way to integrate Google's reCAPTCHA into Angular applications. It supports both reCAPTCHA v2 and v3, allowing developers to add CAPTCHA verification to forms and other interactive elements to enhance security.

What are ng-recaptcha's main functionalities?

Basic reCAPTCHA v2 Integration

This feature allows you to integrate the basic reCAPTCHA v2 into your Angular application. The component listens for the resolved event to handle the CAPTCHA response.

import { Component } from '@angular/core';

@Component({
  selector: 'app-recaptcha',
  template: '<re-captcha (resolved)="resolved($event)" siteKey="your-site-key"></re-captcha>'
})
export class RecaptchaComponent {
  resolved(captchaResponse: string) {
    console.log(`Resolved captcha with response: ${captchaResponse}`);
  }
}

reCAPTCHA v3 Integration

This feature demonstrates how to use reCAPTCHA v3, which does not require user interaction. Instead, it generates a token based on user behavior, which can be used for verification.

import { Component } from '@angular/core';
import { ReCaptchaV3Service } from 'ng-recaptcha';

@Component({
  selector: 'app-recaptcha-v3',
  template: '<button (click)="executeAction()">Execute reCAPTCHA v3</button>'
})
export class RecaptchaV3Component {
  constructor(private recaptchaV3Service: ReCaptchaV3Service) {}

  executeAction() {
    this.recaptchaV3Service.execute('importantAction').subscribe((token) => {
      console.log(`Token received: ${token}`);
    });
  }
}

Invisible reCAPTCHA

This feature shows how to implement invisible reCAPTCHA, which is triggered programmatically rather than by user interaction. This is useful for forms where you want to minimize user friction.

import { Component } from '@angular/core';

@Component({
  selector: 'app-invisible-recaptcha',
  template: '<re-captcha (resolved)="resolved($event)" siteKey="your-site-key" size="invisible"></re-captcha><button (click)="executeCaptcha()">Submit</button>'
})
export class InvisibleRecaptchaComponent {
  resolved(captchaResponse: string) {
    console.log(`Resolved captcha with response: ${captchaResponse}`);
  }

  executeCaptcha() {
    // Trigger the invisible reCAPTCHA
  }
}

Other packages similar to ng-recaptcha

ngx-captcha

ngx-captcha is another Angular library for integrating Google's reCAPTCHA. It supports both reCAPTCHA v2 and v3, similar to ng-recaptcha. However, ngx-captcha offers more customization options and additional features like language support and multiple CAPTCHA instances on a single page.

angular-google-recaptcha

angular-google-recaptcha is a lightweight Angular package for adding Google's reCAPTCHA to your application. It is simpler and less feature-rich compared to ng-recaptcha, making it suitable for projects that require basic CAPTCHA functionality without additional complexity.

README

Angular component for Google reCAPTCHA

ng-recaptcha

A simple, configurable, easy-to-start component for handling reCAPTCHA.

Table of contents

1. Installation
2. Basic Usage
   • Playground
3. Working with @angular/forms
4. API
   • Input Options
   • Events
   • Methods
5. Examples
   • Configuring the component globally
   • Specifying a different language
   • Loading the reCAPTCHA API by yourself
   • Usage with required in forms
   • Working with invisible reCAPTCHA
   • Resizing
   • SystemJS configuration
   • Loading from a different location
   • Specifying nonce for Content-Security-Policy

Installation

The easiest way is to install trough npm:

npm i ng-recaptcha --save

Basic Usage (see in action)

To start with, you need to import the RecaptchaModule (more on that later):

// app.module.ts
import { RecaptchaModule } from 'ng-recaptcha';
// if you need forms support:
// import { RecaptchaFormsModule } from 'ng-recaptcha/forms';
import { BrowserModule }  from '@angular/platform-browser';
import { MyApp } from './app.component.ts';

@NgModule({
  bootstrap: [MyApp],
  declarations: [MyApp],
  imports: [
    BrowserModule,
    RecaptchaModule,
    // RecaptchaFormsModule, // if you need forms support
  ],
})
export class MyAppModule { }

Once you have done that, the rest is simple:

// app.component.ts
import { Component } from '@angular/core';

@Component({
    selector: 'my-app',
    template: `<re-captcha (resolved)="resolved($event)" siteKey="YOUR_SITE_KEY"></re-captcha>`,
}) export class MyApp {
    resolved(captchaResponse: string) {
        console.log(`Resolved captcha with response ${captchaResponse}:`);
    }
}

// boot.ts
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { MyAppModule } from './app.module.ts';

platformBrowserDynamic().bootstrapModule(MyAppModule);

Playground

You can also play with this Stackblitz demo to get a feel of how this component can be used.

Working with @angular/forms

There are two modules available for you:

import { RecaptchaModule } from 'ng-recaptcha';
import { RecaptchaFormsModule } from 'ng-recaptcha/forms';

If you want your <re-captcha> element to work correctly with [(ngModel)] directive, you need to import the RecaptchaFormsModule into your application module (pretty much like with Angular own '@angular/forms' module).

If you do not rely on Angular forms in your project, you should use the "no-forms" module version, as it does not require the @angular/forms package to be bundled with your code.

API

Input Options

The component supports this options:

• siteKey
• theme
• type
• size
• tabIndex
• badge

They are all pretty well described either in the reCAPTCHA docs, or in the invisible reCAPTCHA docs, so I won't duplicate it here.

Besides specifying these options on the component itself, you can provide a global <re-captcha> configuration - see Configuring the component globally section below.

Events

• resolved(response: string). Occurs when the captcha resolution value changed. When user resolves captcha, use response parameter to send to the server for verification. This parameter is equivalent to calling grecaptcha.getResponse.

  If the captcha has expired prior to submitting its value to the server, the component will reset the captcha, and trigger the resolved event with response === null.

Methods

• reset(). Performs a manual captcha reset. This method might be useful if your form validation failed, and you need the user to re-enter the captcha.
• execute(). Executes the invisible recaptcha. Does nothing if component's size is not set to "invisible". See Invisible reCAPTCHA developers guide for more information.

Examples

Configuring the component globally (see in action)

Some properties are global - including siteKey, size, and others. You can provide them at the module-level using the RECAPTCHA_SETTINGS provider:

import { RECAPTCHA_SETTINGS, RecaptchaSettings } from 'ng-recaptcha';

@NgModule({
  providers: [
    {
      provide: RECAPTCHA_SETTINGS,
      useValue: { siteKey: '<YOUR_KEY>' } as RecaptchaSettings,
    },
  ],
}) export class MyModule { }

Global properties can be overridden on a case-by-case basis - the values on the <re-captcha> component itself take precedence over global settings.

Specifying a different language (see in action)

<re-captcha> supports various languages. By default recaptcha will guess the user's language itself (which is beyond the scope of this lib). But you can override this behavior and provide a specific language to use. The language setting is global, though, and cannot be set on a per-captcha basis. It can be provided like this:

import { RECAPTCHA_LANGUAGE } from 'ng-recaptcha';

@NgModule({
  providers: [
    {
      provide: RECAPTCHA_LANGUAGE,
      useValue: 'fr', // use French language
    },
  ],
}) export class MyModule { }

You can find the list of supported languages in reCAPTCHA docs.

Loading the reCAPTCHA API by yourself (see in action)

By default, the component assumes that the reCAPTCHA API loading will be handled by the RecaptchaLoaderService. However, you can override that by providing your instance of this service to the Angular DI.

The below code snippet is an example of how such a provider can be implemented.

TL;DR: there should be an Observable that eventually resolves to a grecaptcha-compatible object (e.g. grecaptcha itself).

<script src="https://www.google.com/recaptcha/api.js?render=explicit&amp;onload=onloadCallback"></script>

<script>
    // bootstrap the application once the reCAPTCHA api has loaded
    function onloadCallback() {
        System.import('app').catch(function(err) { console.error(err); });
    }
</script>

import { RecaptchaLoaderService } from 'ng-recaptcha';

@Injectable()
export class PreloadedRecaptchaAPIService {
  public ready: Observable<ReCaptchaV2.ReCaptcha>;

  constructor() {
    let readySubject = new BehaviorSubject<ReCaptchaV2.ReCaptcha>(grecaptcha);
    this.ready = readySubject.asObservable();
  }
}

@NgModule({
  providers: [
    {
      provide: RecaptchaLoaderService,
      useValue: new PreloadedRecaptchaAPIService(),
    },
  ],
}) export class MyModule { }

Usage with required in forms (see in action)

It's very easy to put <re-captcha> in an Angular form and have it required - just add the required attribute to the <re-captcha> element. Do not forget to import RecaptchaFormsModule from 'ng-recaptcha/forms'!

@Component({
  selector: 'my-form',
  template: `
  <form>
    <re-captcha
      [(ngModel)]="formModel.captcha"
      name="captcha"
      required
      siteKey="YOUR_SITE_KEY"
    ></re-captcha>
  </form>`,
}) export class MyForm {
  formModel = new MyFormModel();
}

A similar approach can be taken for reactive forms:

@Component({
  selector: 'my-reactive-form',
  template: `
    <form [formGroup]="reactiveForm">
      <re-captcha formControlName="recaptchaReactive"></re-captcha>
      <button [disabled]="reactiveForm.invalid">Submit</button>
    </form>
  `,
}) export class MyReactiveForm {
  reactiveForm: FormGroup;

  ngOnInit() {
    this.reactiveForm = new FormGroup({
      recaptchaReactive: new FormControl(null, Validators.required)
    });
  }
}

Working with invisible reCAPTCHA (see in action)

Working with invisible reCAPTCHA is almost the same as with regular one. First, you need to provide the right size:

<re-captcha size="invisible" ...></re-captcha>

You will also need to invoke the "execute()" method manually. This can be done by either obtaining a reference to RecaptchaComponent via @ViewChild(), or by using inline template reference:

<re-captcha #captchaRef="reCaptcha" ...></re-captcha>
...
<button (click)="captchaRef.execute()">Submit</button>

Normally you would only submit a form when recaptcha response has been received. This can be achieved by reacting to (resolved) event and invoking submit logic when the captcha response is truthy (this will not try to submit the form when recaptcha response has expired). A sample implementation would look like this:

@Component({
  selector: 'my-form',
  template: `
  <form>
    <re-captcha
      #captchaRef="reCaptcha"
      siteKey="YOUR_SITE_KEY"
      size="invisible"
      (resolved)="$event && submit($event)"
    ></re-captcha>
    <button (click)="captchaRef.execute()">Submit</button>
  </form>`,
}) export class MyForm {
  public submit(captchaResponse: string): void {
    this.http.post({
      captcha: captchaResponse,
      /* ... */
    });
  }
}

Resizing

Making reCAPTCHA responsive is sometimes necessary, especially when working with mobile devices. You can use css-transforms to achieve that as in this StackOverflow answer, which is also ell-described in this blog post. You can also take a look at a live example of how this might be implemented. This boils down to

<div style="transform:scale(0.7);transform-origin:0;">
  <re-captcha></re-captcha>
</div>

SystemJS configuration

To configure the package to work with SystemJS, you would configure it approximately like that (assuming you've installed ng-recaptcha using npm):

// SystemJS config file
(function () {
  System.config({
    paths: {
      'npm:': '/node_modules/',
    },
    map: {
      'ng-recaptcha': 'npm:ng-recaptcha',
    },
    packages: {
      'ng-recaptcha': { main: './index.js' },
    },
  });
})();

Loading from a different location

Since "google.com" domain might be unavailable in some countries, reCAPTCHA core team has a solution for that - using "recaptcha.net" domain. You can configure the component to use that by providing the RECAPTCHA_BASE_URL token, for example:

import { RECAPTCHA_BASE_URL } from 'ng-recaptcha';

@NgModule({
  providers: [
    {
      provide: RECAPTCHA_BASE_URL,
      useValue: 'https://recaptcha.net/recaptcha/api.js', // use recaptcha.net script source for some of our users
    },
  ],
}) export class MyModule { }

Specifying nonce for Content-Security-Policy

Per reCAPTCHA FAQ on CSP, the recommended approach for that is to supply nonce to the script tag. This is possible by providing the RECAPTCHA_NONCE token, for example:

import { RECAPTCHA_NONCE } from 'ng-recaptcha';

@NgModule({
  providers: [
    {
      provide: RECAPTCHA_NONCE,
      useValue: '<YOUR_NONCE_VALUE>',
    },
  ],
}) export class MyModule { }

Changelog

4.2.0 (2018-10-24)

Features

• component: add the ability to provide nonce to the script tag (8f55b19), closes #100
• component: allow to specify a base url for loading recaptcha (df505fd), closes #101

<a name="4.1.1"></a>