ng-recaptcha-2
Advanced tools
Parent project (ng-recaptcha)
A simple, configurable, easy-to-start component for handling reCAPTCHA v2 and v3.
@angular/formsrequired in formsThe easiest way is to install through yarn or npm:
yarn add ng-recaptcha-2
npm i ng-recaptcha-2 --save
The below applies to reCAPTCHA v2, for basic usage with reCAPTCHA v3 scroll down to here.
To start with, you need to import the RecaptchaModule (more on that later):
// app.module.ts
import { RecaptchaModule } from "ng-recaptcha-2";
// if you need forms support:
// import { RecaptchaModule, RecaptchaFormsModule } from 'ng-recaptcha-2';
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}`);
}
}
// main.ts
import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
import { MyAppModule } from "./app.module.ts";
platformBrowserDynamic().bootstrapModule(MyAppModule);
reCAPTCHA v3 introduces a different way of bot protection. To work with v3 APIs, ng-recaptcha provides a service (as opposed to a component). To start with, you need to import the RecaptchaV3Module and provide your reCAPTCHA v3 site key using RECAPTCHA_V3_SITE_KEY injection token:
import { BrowserModule } from "@angular/platform-browser";
import { RECAPTCHA_V3_SITE_KEY, RecaptchaV3Module } from "ng-recaptcha-2";
import { MyApp } from "./app.component.ts";
@NgModule({
bootstrap: [MyApp],
declarations: [MyApp],
imports: [BrowserModule, RecaptchaV3Module],
providers: [{ provide: RECAPTCHA_V3_SITE_KEY, useValue: "<YOUR_SITE_KEY>" }],
})
export class MyAppModule {}
In order to execute a reCAPTCHA v3 action, import the ReCaptchaV3Service into your desired component:
import { ReCaptchaV3Service } from 'ng-recaptcha-2';
@Component({
selector: 'recaptcha-demo',
template: `
<button (click)="executeImportantAction()">Important action</button>
`,
})
export class RecaptchaV3DemoComponent {
constructor(
private recaptchaV3Service: ReCaptchaV3Service,
) {
}
public executeImportantAction(): void {
this.recaptchaV3Service.execute('importantAction')
.subscribe((token) => this.handleToken(token));
}
As always with subscriptions, please don't forget to unsubscribe.
❗️ Important note: If your site uses both v2 and v3, then you should always provide RECAPTCHA_V3_SITE_KEY (even in modules that only rely on v2 functionality). This will prevent bugs in your code by allowing ng-recaptcha to follow reCAPTCHA development guidelines properly (this one in particular).
A more advanced v3 usage scenario includes listening to all actions and their respectively emitted tokens. This is covered later on this page.
You can also play with this Stackblitz demo to get a feel of how this component can be used.
@angular/formsThere are two modules available for you:
import { RecaptchaModule, RecaptchaFormsModule } from "ng-recaptcha-2";
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).
The component supports this options:
siteKeythemetypesizetabIndexbadgeThey are all pretty well described either in the reCAPTCHA docs, or in the invisible reCAPTCHA docs, so I won't duplicate it here.
One additional option that component accepts is errorMode. You can learn more about it in the Handling errors section below.
Besides specifying these options on the component itself, you can provide a global <re-captcha> configuration - see Configuring the component globally section below.
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.
errored(errorDetails: RecaptchaErrorParameters). Occurs when reCAPTCHA encounters an error (usually a connectivity problem) if and only if errorMode input has been set to "handled".
errorDetails is a simple propagation of any arguments that the original error-callback has provided, and is documented here for the purposes of completeness and future-proofing. This array will most often (if not always) be empty. A good strategy would be to rely on just the fact that this event got triggered, and show a message to your app's user telling them to retry.
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.ng-recaptcha-2 version | Supported Angular versions |
|---|---|
15.x.x | 19.x.x |
14.x.x | 18.x.x |
ng-recaptcha version | Supported Angular versions |
|---|---|
13.x.x | 17.x.x |
12.x.x | 16.x.x |
11.x.x | 15.x.x |
10.x.x | 14.x.x |
9.x.x | 13.x.x |
8.x.x | 12.x.x |
7.x.x | 11.x.x |
⬆️ Starting with ng-recaptcha@7, only one version of Angular will be supported | |
6.x.x | 6.x.x || 7.x.x || 8.x.x || 9.x.x || 10.x.x |
5.x.x | 6.x.x || 7.x.x || 8.x.x |
4.x.x | 6.x.x || 7.x.x |
3.x.x | 4.x.x || 5.x.x |
2.x.x | 2.x.x || 4.x.x |
1.x.x | 2.x.x |
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-2";
@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.
<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 by setting the "hl" search param in the onBeforeLoad hook.
Note, that the language setting is global, and cannot be set on a per-captcha basis.
A good way to synchronize reCAPTCHA language with the rest of your application is relying on LOCALE_ID value like so:
import { LOCALE_ID } from "@angular/core";
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha-2";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useFactory: (locale: string) => ({
onBeforeLoad(url) {
url.searchParams.set("hl", locale);
return { url };
},
}),
deps: [LOCALE_ID],
},
],
})
export class MyModule {}
Alternatively, a specific language can be provided like so:
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha-2";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useValue: {
onBeforeLoad(url) {
url.searchParams.set("hl", "fr"); // use French language
return { url };
},
},
},
],
})
export class MyModule {}
You can find the list of supported languages in reCAPTCHA docs.
Sometimes reCAPTCHA encounters an error, which is usually a network connectivity problem. It cannot continue until connectivity is restored. By default, reCAPTCHA lets the user know that an error has happened (it's a built-in functionality of reCAPTCHA itself, and this lib is not in control of it). The downside of such behavior is that you, as a developer, don't get notified about this in any way. Opting into such notifications is easy, but comes at a cost of assuming responsibility for informing the user that they should retry. Here's how you would do this:
import { Component } from "@angular/core";
@Component({
selector: "my-app",
template: `<re-captcha (resolved)="resolved($event)" (errored)="errored($event)" errorMode="handled"></re-captcha>`,
})
export class MyApp {
resolved(captchaResponse: string) {
console.log(`Resolved captcha with response: ${captchaResponse}`);
}
errored() {
console.warn(`reCAPTCHA error encountered`);
}
}
You can see this in action by navigating to either basic example demo or invisible demo and trying to interact with reCAPTCHA after setting the network to "Offline".
The errorMode input has two possible values -- "handled" and "default", with latter being the default as the name suggests. Not specifying errorMode, or setting it to anything other than "handled" will not invoke your (errored) callback, and will instead result in default reCAPTCHA functionality.
The (errored) callback will propagate all of the parameters that it receives from grecaptcha['error-callback'] (which might be none) as an array.
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&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-2";
@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 {}
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-2'!
@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 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,
/* ... */
});
}
}
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>
To configure the package to work with SystemJS, you would configure it approximately like that (assuming you've installed ng-recaptcha-2 using npm):
// SystemJS config file
(function () {
System.config({
paths: {
"npm:": "/node_modules/",
},
map: {
"ng-recaptcha-2": "npm:ng-recaptcha-2",
},
packages: {
"ng-recaptcha-2": { main: "./index.js" },
},
});
})();
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 using the onBeforeLoad hook of RECAPTCHA_LOADER_OPTIONS, for example:
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha-2";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useValue: {
onBeforeLoad(_url) {
return {
url: new URL("https://www.recaptcha.net/recaptcha/api.js"), // use recaptcha.net script source for some of our users
};
},
},
},
],
})
export class MyModule {}
Per reCAPTCHA FAQ on CSP, the recommended approach for that is to supply nonce to the script tag. This is possible by providing the nonce as part of the onBeforeLoad hook of RECAPTCHA_LOADER_OPTIONS, for example
import { RECAPTCHA_LOADER_OPTIONS } from "ng-recaptcha-2";
@NgModule({
providers: [
{
provide: RECAPTCHA_LOADER_OPTIONS,
useValue: {
onBeforeLoad(_url) {
return {
url,
nonce: "<YOUR_NONCE_VALUE>",
};
},
},
},
],
})
export class MyModule {}
More often than not you will need to only get a reCAPTCHA token with the action the user is currently taking, and submit it to the backend at that time. However, having a single listener for all events will be desirable.
There is an Observable exactly for that purpose: ReCaptchaV3Service.onExecute. It emits a value every time a token is received from reCAPTCHA. The shape of payload it operates on is defined via OnExecuteData interface:
interface OnExecuteData {
action: string;
token: string;
}
where action is the name of the action that has been executed, and token is what reCAPTCHA v3 provided when executing that action.
Here's how you would potentially set this up:
import { OnExecuteData, ReCaptchaV3Service } from "ng-recaptcha-2";
@Component({
selector: "my-component",
templateUrl: "./v3-demo.component.html",
})
export class MyComponent implements OnInit, OnDestroy {
private subscription: Subscription;
constructor(private recaptchaV3Service: ReCaptchaV3Service) {}
public ngOnInit() {
this.subscription = this.recaptchaV3Service.onExecute.subscribe((data: OnExecuteData) => {
this.handleRecaptchaExecute(data.action, data.token);
});
}
public ngOnDestroy() {
if (this.subscription) {
this.subscription.unsubscribe();
}
}
}
There are a couple things to keep in mind:
onExecute will trigger for all actions. If you only need to bulk-process some actions, and not others - you will have to apply filtering yourself.onExecute observable will provide you with all the events emitted after you have subscribed to it - it doesn't keep references to the previously emitted actions. So make sure you add such a subscription as early in your code as you feel is necessary.onExecute does not emit anything for when a grecaptcha error occurs. Use onExecuteError Observable for that.If your use-case needs to load the reCAPTCHA v2/v3 key from the backend (as opposed to specifying it in-code during build time), the Angular-idiomatic way to do that is by relying on APP_INITIALIZER. You can find an example of how this could look like below, and you can also consult the source code for the demo site.
// config.service.ts
import { Injectable } from "@angular/core";
@Injectable({
providedIn: "root",
})
export class ConfigService {
public recaptchaSiteKeyV2: string | null = null;
public recaptchaSiteKeyV3: string | null = null;
public async loadConfig(): Promise<void> {
const { siteKeyV2, siteKeyV3 } = await fetchConfig(/* some API call */);
this.recaptchaSiteKeyV2 = siteKeyV2;
this.recaptchaSiteKeyV3 = siteKeyV3;
}
}
// app.module.ts
import { APP_INITIALIZER, NgModule } from "@angular/core";
import { RECAPTCHA_SETTINGS, RecaptchaSettings, RECAPTCHA_V3_SITE_KEY } from "ng-recaptcha-2";
import { ConfigService } from "./config.service";
function appLoadFactory(config: ConfigService) {
return () => config.loadConfig().then(() => console.log(`config resolved`, config));
}
@NgModule({
providers: [
{
provide: RECAPTCHA_V3_SITE_KEY,
useFactory: (config: ConfigService) => {
return config.recaptchaSiteKeyV3;
},
deps: [ConfigService],
},
{
provide: RECAPTCHA_SETTINGS,
useFactory: (config: ConfigService): RecaptchaSettings => {
return { siteKey: config.recaptchaSiteKeyV2 };
},
deps: [ConfigService],
},
{
provide: APP_INITIALIZER,
useFactory: appLoadFactory,
deps: [ConfigService],
multi: true,
},
],
})
export class AppModule {}
To start with, this is not strictly under ng-recaptcha-2 library control.
However, there is a way of doing so (albeit subject to certain conditions).
Please refer to the FAQ section of reCAPTCHA documentation to get an idea of what you're required to do.
15.0.1 (2024-11-22)
<a name="14.0.0"></a>
resolved event (25d4246)ngOnDestroy (b31d57f), closes #12resolved(null) event when recaptcha expires (491d99a), closes #11RecaptchaV3Module (c93b99c)execute errors for reCAPTCHA v3 (c7d02ce), closes #194forRoot() method as deprecated (dea31e5)OpaqueToken with InjectionToken (2b7db9b)README.md file back to a proper symlink (e0c5c99)[@types](https://github.com/types)/grecaptcha a non-optional dependency (bc5ad51), closes #205of operator (3e0bda6), closes #95error output in favor of errored (6b002bb)exportAs annotation (3e2e217)RECAPTCHA_LOADER_OPTIONS injection token as a way of manipulating script load parameters (such as base URL, language, trusted types, WAF, etc) (b3c7213)badge property (5a16430), closes #30nonce to the script tag (8f55b19), closes #100forRoot method (514beaf)forRoot() when importing RecaptchaModule (7fb97fb), closes #113 #116[@types](https://github.com/types)/grecaptcha as optional dependency (85fbfba)"[@types](https://github.com/types)/grecaptcha" optional dependency version to ^3 (e1ee7b9)ng-recaptcha to v12.x.x to retain support for a previous Angular versionng-recaptcha to v11.x.x to retain support for a previous Angular versionRecaptchaModule.forRoot() method has been obsolete since v4.1.0 (since it has no longer been required). It is now removed. To migrate your code, simply use RecaptchaModule where you previously used RecaptchaModule.forRoot()ng-recaptcha/forms entry point has been removed. RecaptchaFormsModule and RecaptchaValueAccessorDirective should now be imported directly from ng-recaptchatslib is now a package dependency to ensure minimum possible bundle size. If your project doesn't yet have a dependency on tslib, run npm install -D tslib@^1.9.0 (or yarn add -D tslib@^1.9.0 if you use yarn)@angular/core has been bumped to ^6.0.0recaptcha to re-captchaRecaptchaNoFormsModule should instead use import { RecaptchaModule } from 'ng-recaptcha'. Users of v1 RecaptchaModule should also import { RecaptchaFormsModule } from 'ng-recaptcha/forms'. SystemJS users must also re-setup module "main" file to index.js<a name="13.2.1"></a>
FAQs
Angular component for Google reCAPTCHA for Angular v18 and onwards
The npm package ng-recaptcha-2 receives a total of 9,660 weekly downloads. As such, ng-recaptcha-2 popularity was classified as popular.
We found that ng-recaptcha-2 demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.