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