Cloudflare Turnstile Component for Angular

ngx-turnstile

An easy to use component for implementing Cloudflare Turnstile in Angular.

Installation

Add this library to your Angular project using npm or yarn.

yarn add ngx-turnstile
npm install ngx-turnstile --save

Quickstart

NgxTurnstileComponent is a standalone component. Import it directly into any standalone component (or NgModule) that needs it:

// app.component.ts
import { Component } from "@angular/core";
import { NgxTurnstileComponent } from "ngx-turnstile";

@Component({
  selector: "my-app",
  standalone: true,
  imports: [NgxTurnstileComponent],
  template: `<ngx-turnstile [siteKey]="siteKey" (resolved)="sendCaptchaResponse($event)" theme="auto" [tabIndex]="0"></ngx-turnstile>`,
})
export class MyApp {
  siteKey = "<YOUR_SITE_KEY>";

  sendCaptchaResponse(captchaResponse: string | null) {
    console.log(`Resolved captcha with response: ${captchaResponse}`);
  }
}

If you use NgModules, you can instead import NgxTurnstileModule:

// app.module.ts
import { NgxTurnstileModule } from "ngx-turnstile";
import { BrowserModule } from "@angular/platform-browser";
import { MyApp } from "./app.component.ts";

@NgModule({
  bootstrap: [MyApp],
  declarations: [MyApp],
  imports: [BrowserModule, NgxTurnstileModule],
})
export class MyAppModule {}

Usage with @angular/forms

Import both NgxTurnstileModule and NgxTurnstileFormsModule modules in your app module.

import { NgxTurnstileModule, NgxTurnstileFormsModule } from "ngx-turnstile";

Then import either FormsModule or ReactiveFormsModule from @angular/forms depending on the type of form you want to use.

You can then use the ngModel, formControl or formControlName directives on the component depending on which module you imported from @angular/forms.

Reactive Form Example

<ngx-turnstile [siteKey]="siteKey" theme="auto" [formControl]="tokenControl"></ngx-turnstile>

Template Driven Form Example

<ngx-turnstile [siteKey]="siteKey" theme="light" [(ngModel)]="token"></ngx-turnstile>

The component is read-only, meaning that you should not update the control with a custom value. Updating the control value will reset the component.

API

Inputs

The letter cases are adapted to camelCase to facilitate easy migration from ng-recaptcha. Each input maps to the corresponding Cloudflare render parameter.

Input	Type	Default	Description
siteKey	string (required)	—	Your widget's sitekey, created when the widget is created.
action	string	—	A customer value to differentiate widgets under the same sitekey (up to 32 chars: alphanumeric, _, -). Returned upon validation.
cData	string	—	A customer payload attached to the challenge (up to 255 chars: alphanumeric, _, -). Returned upon validation.
theme	'light' | 'dark' | 'auto'	'auto'	Widget theme. auto respects the visitor's preference.
language	string	'auto'	auto, or an ISO 639-1 code (e.g. en) / language-country code (e.g. en-US). See supported languages.
tabIndex	number	0	The tabindex of Turnstile's iframe for accessibility.
appearance	'always' | 'execute' | 'interaction-only'	'always'	Controls when the widget is visible. See Appearance modes.
execution	'render' | 'execute'	'render'	Controls when to obtain the token. See Execution modes.
retry	'auto' | 'never'	'auto'	Whether the widget automatically retries to obtain a token on failure.
retryInterval	number	8000	When retry is auto, the time between retry attempts in ms. Positive integer less than 900000.
refreshExpired	'auto' | 'manual' | 'never'	'auto'	Behavior when the token expires.
refreshTimeout	'auto' | 'manual' | 'never'	'auto'	Behavior when an interactive challenge times out. Only applies to widgets in Managed mode.
size	'normal' | 'flexible' | 'compact'	'normal'	Widget size.
responseField	boolean	true	Whether to create a hidden input element containing the response token.
responseFieldName	string	'cf-turnstile-response'	Name of the hidden input element.
feedbackEnabled	boolean	true	Allows Cloudflare to gather visitor feedback upon widget failure.
offlabelShowPrivacy	boolean	true	Displays the privacy link for unbranded Turnstile widgets.
offlabelShowHelp	boolean	true	Displays the help link for unbranded Turnstile widgets.

Outputs

Output	Payload	Description
resolved	string | null	Emitted when the CAPTCHA resolution value changes. Emits null when the widget is reset (e.g. on token expiry).
errored	string | null	Emitted when the widget returns an error code.
beforeInteractive	void	Emitted before the challenge enters interactive mode.
afterInteractive	void	Emitted when the challenge has left interactive mode.
unsupported	void	Emitted when the visitor's browser is not supported by Turnstile.
timeout	void	Emitted when an interactive challenge is not solved within the allotted time.

When the token expires, the component automatically resets the widget and emits resolved(null). Use refreshExpired to opt into Cloudflare's native refresh handling.

Example

For those who prefer examples over documentation, simply clone the repository and run

$ yarn install
$ ng build ngx-turnstile
$ ng serve ngx-turnstile-demo