recaptcha-angular

Lightweight, zero-dependency Angular component for Google reCAPTCHA v2 (checkbox) and v3 (score-based) with full TypeScript support, standalone APIs, and ControlValueAccessor (ngModel / reactive forms) integration. Switch between v2 and v3 with a single version input.

Coverage (generated locally with npm run test:coverage, no external service):

Statements	Branches	Functions	Lines

This is the Angular port of recaptcha-vue. Same behaviour, Angular idioms.

---

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Token expiry and resetting
• Inputs
• Outputs
• Public methods
• reCAPTCHA v3
• Forms integration
• RecaptchaService
• Server-side verification
• Multiple instances on one page
• Local development
• License

---

Features

• v2 and v3 in one component: version="v2" (default) or version="v3"
• Standalone component (Angular 17+), no NgModule required
• TypeScript: full types for inputs, outputs, and the public methods
• RecaptchaService: signal-based token & isVerified state
• Forms: implements ControlValueAccessor, works with [(ngModel)] and formControlName
• Multiple instances: safe to use more than one widget per page
• Theming: light / dark, normal / compact
• Language: pass any BCP 47 code (hl param)
• Load timeout: emits error if the script never loads
• Ivy partial-compilation build via ng-packagr, zero runtime dependencies

---

Requirements

	Version
Node.js	>=20.19.0 (see .nvmrc)
Angular	>=17.0.0 (peer dependency)

@angular/core, @angular/common, and @angular/forms are peer dependencies.

---

Installation

npm install recaptcha-angular

---

Quick start

1. Get your reCAPTCHA v2 keys

Register at https://www.google.com/recaptcha/admin. Choose reCAPTCHA v2 -> "I'm not a robot" Checkbox.

Test keys (always pass, never use in production): Site key: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI Secret key: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

2. Use the component

import { Component } from '@angular/core'
import { RecaptchaComponent, RecaptchaService } from 'recaptcha-angular'

@Component({
  selector: 'app-form',
  standalone: true,
  imports: [RecaptchaComponent],
  providers: [RecaptchaService],
  template: `
    <recaptcha-v2
      sitekey="YOUR_SITE_KEY"
      (verify)="captcha.onVerify($event)"
      (expire)="captcha.onExpire()"
      (error)="captcha.onError()"
    ></recaptcha-v2>
    <button [disabled]="!captcha.isVerified()">Submit</button>
  `,
})
export class FormComponent {
  constructor(public captcha: RecaptchaService) {}
}

---

Token expiry and resetting

A verified token is only valid for about 2 minutes (Google's own limit), and it's single-use: once you've submitted it to your backend, that exact token cannot be verified again, whether verification succeeded or failed. Two failure modes follow directly from that:

1. The user waits too long. The checkbox stays visually "checked," but the token behind it has expired. Handle this with the (expire) output (wired to RecaptchaService.onExpire), which flips isVerified() back to false so your submit button disables itself again instead of sending a dead token.
2. The user submits, something else fails, they retry. Say the token verifies fine but a different field fails server-side validation. If you don't reset the widget, the user fixes that field and resubmits the same token, which your backend now rejects, and it looks like reCAPTCHA itself is broken.

The fix for both is the same one-liner, and it belongs in every code path that leaves the form, success or failure. Grab the component with a template ref and call reset():

<recaptcha-v2 #captcha sitekey="..."></recaptcha-v2>

@ViewChild('captcha') captcha!: RecaptchaComponent
// ...
this.captcha.reset()

---

Inputs

Input	Type	Default	Description
sitekey	string	required	Your reCAPTCHA site key
version	'v2' | 'v3'	'v2'	Which reCAPTCHA to use. See reCAPTCHA v3
action	string	'submit'	v3 only. Default action when execute() is called with no argument
theme	'light' | 'dark'	'light'	v2 only. Widget color scheme
size	'normal' | 'compact'	'normal'	v2 only. Widget size
tabindex	number	0	v2 only. Tab index
loadingTimeout	number	30000	ms before error fires if the script never loads
language	string	''	BCP 47 language code, e.g. 'fr', 'ar'
badge	'bottomright' | 'bottomleft' | 'inline'	'bottomright'	v2 only. Badge position (invisible size only)
hideBadge	boolean	false	v3 only. Hide the floating badge (see the legal note in reCAPTCHA v3)
isolated	boolean	false	v2 only. Isolate widget from others on the page

---

Outputs

Output	Payload	Fires when
verify	string	User completed the challenge; token ready to send to server
expire	void	Token expired; user must re-verify
error	void	Widget or network error, or load timeout
widgetId	number	Widget rendered (internal widget id)

"Ready to send to server" is doing a lot of work in that first row. See Client state is not verification for why sending it isn't the same as being verified.

---

Public methods (via template ref)

<recaptcha-v2 #captcha sitekey="..."></recaptcha-v2>
<button (click)="captcha.reset()">Retry</button>

• reset() resets the widget (v2) or clears the token (v3)
• execute(action?) returns Promise<string>. On v3 it runs the challenge for the action and resolves with the token; on v2 it triggers the challenge and resolves when the next verify fires
• getResponse() returns the current token string

---

reCAPTCHA v3

reCAPTCHA v3 is score-based and renders no widget: there is nothing to click. Set version="v3" and get a token on demand by calling execute(action), usually right before you submit. (verify) still fires with the token, so RecaptchaService works exactly as it does for v2.

import { Component, ViewChild } from '@angular/core'
import { RecaptchaComponent } from 'recaptcha-angular'

@Component({
  selector: 'app-login',
  standalone: true,
  imports: [RecaptchaComponent],
  template: `
    <form (ngSubmit)="submit()">
      <!-- No visible widget on v3, just the floating badge -->
      <recaptcha-v2 #captcha sitekey="YOUR_V3_SITE_KEY" version="v3"></recaptcha-v2>
      <button type="submit">Log in</button>
    </form>
  `,
})
export class LoginComponent {
  @ViewChild('captcha') captcha!: RecaptchaComponent

  async submit() {
    const token = await this.captcha.execute('login')
    await fetch('/api/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ 'g-recaptcha-response': token }),
    })
  }
}

Notes specific to v3:

• Get a fresh token per submit. v3 tokens are single-use and expire in about 2 minutes, so call execute() at submit time, not on init.
• The badge and the law. v3 shows a floating "protected by reCAPTCHA" badge. You may hide it with hideBadge, but only if you then display the required legal text yourself.
• Server-side gives you a score. siteverify returns score (0.0 to 1.0) and action. Reject low scores and confirm the action matches.
• One version per page. Rendering a v2 and a v3 instance on the same page is not supported (they share Google's single grecaptcha global). Pick one.

---

Forms integration

The verified token is the control value, so the component drops straight into template-driven or reactive forms:

<!-- template-driven -->
<recaptcha-v2 sitekey="..." [(ngModel)]="token" name="captcha"></recaptcha-v2>

<!-- reactive -->
<recaptcha-v2 sitekey="..." formControlName="captcha"></recaptcha-v2>

Setting the bound value to '' resets the widget. Any other value is owned by grecaptcha and cannot be written programmatically, so it's ignored.

---

RecaptchaService

Signal-based state, mirroring the Vue composable / React hook. Provide it at the component level (not root) so each form gets its own instance.

captcha.token()       // Signal<string>: current token ('' when expired / error)
captcha.isVerified()  // computed Signal<boolean> (client-side only, see below)
captcha.onVerify(t)   // wire to (verify)
captcha.onExpire()    // wire to (expire)
captcha.onError()     // wire to (error)
captcha.reset()       // clear the tracked state (call component.reset() too)

Client state is not verification

---

Server-side verification

Always verify the token on your backend against https://www.google.com/recaptcha/api/siteverify with your secret key. See examples/contact.component.ts for a full form, and the recaptcha-vue repo for a ready-made Laravel controller and validation rule.

---

Multiple instances on one page

Each <recaptcha-v2> instance manages its own unique widget id and global callback names, so you can safely render more than one widget:

<recaptcha-v2 [sitekey]="siteKey" (verify)="onLogin($event)"></recaptcha-v2>
<recaptcha-v2 [sitekey]="siteKey" (verify)="onSignup($event)"></recaptcha-v2>

---

Local development

git clone https://github.com/Souhailmakni/recaptcha-angular.git
cd recaptcha-angular
npm install

Scripts

Command	Description
npm run build	Build the library into dist/recaptcha-angular with ng-packagr
npm test	Run the Karma/Jasmine specs headless once
npm run test:watch	Run the specs in watch mode
npm run test:coverage	Run the specs with coverage and update the README badges
npm run pack	Build, then npm pack the publishable tarball for inspection

Publishing is done from the built output:

npm run build && cd dist/recaptcha-angular && npm publish --access public

---

License

MIT © Souhail Makni