Blazor.Captcha

Blazor.Captcha is a .NET 10 Blazor component library for integrating CAPTCHA widgets (Google reCAPTCHA v2/v3 and hCaptcha) into Blazor WebAssembly and Server applications. It provides reusable components, JSInterop adapters, and flexible configuration for secure user validation.

Features

• Google reCAPTCHA v2: Interactive challenge widget.
• Google reCAPTCHA v3: Background risk scoring and badge.
• hCaptcha: Privacy-focused CAPTCHA alternative.
• Blazor-idiomatic API: Use as Razor components with event callbacks.
• Culture, theme, and position customization.
• AOT compatible and supports .NET 10.
• JSInterop adapters for script management and event handling.
• Extensive logging via ILogger.

Installation

1. Add the NuGet package to your project:

dotnet add package Blazor.Captcha

2. Register required services in your Program.cs:

builder.Services.AddBlazorCaptcha();

Usage

Google reCAPTCHA v2

@using Substantive.Blazor.Captcha

<ReCaptchaV2 SiteKey="your-site-key"
             OnSuccess="HandleSuccess"
             OnExpired="HandleExpired" />

Google reCAPTCHA v3

@using Substantive.Blazor.Captcha

<ReCaptchaV3 SiteKey="your-site-key"
             Position="ReCaptchaV3Position.BottomRight"
             OnSuccess="HandleSuccess" />

hCaptcha

@using Substantive.Blazor.Captcha

<HCaptcha SiteKey="your-hcaptcha-site-key"
          Size="HCaptchaSize.Normal"
          OnSuccess="HandleSuccess"
          OnExpired="HandleExpired" />

Event Callbacks

• OnSuccess: Invoked with the CAPTCHA token when completed.
• OnExpired: Invoked when the challenge expires.

Resetting Captcha

Each component exposes a ResetCaptcha() method to allow users to retry the challenge.

Configuration

• Culture: Set via the Culture parameter (e.g., "en", "fr").
• Theme: Automatically detects dark/light theme for reCAPTCHA v3.
• Position: For reCAPTCHA v3 badge (BottomRight, BottomLeft, Inline).
• Size: For hCaptcha (Normal, Compact, Invisible).

Advanced

• JSInterop adapters (ReCaptchaV2JS, ReCaptchaV3JS, HCaptchaJS) can be injected for direct control.
• Logging extensions for diagnostics.
• Custom JSON converter for widget IDs.