google-react-recaptcha-v2

🛡️ React ReCaptchaV2

A lightweight and developer-friendly React component for rendering an invisible Google reCAPTCHA v2 widget. It supports custom callbacks, localization, badge positioning, and can be triggered programmatically using ref.

✅ Supports TypeScript
✅ Works in development and production environments
✅ Easily integrates with forms or async flows
✅ Minimal and clean API

---

📦 Installation

npm install google-react-recaptcha-v2
# or
yarn add google-react-recaptcha-v2
# or
yarn add google-react-recaptcha-v2

---

🚀 Getting Started

1. Import the Component

import { ReCaptchaV2, ReCaptchaV2Ref } from "google-react-recaptcha-v2";

2. Add the Component to Your Form

import { useRef } from "react";
import { ReCaptchaV2, ReCaptchaV2Ref } from "google-react-recaptcha-v2";

export default function MyForm() {
  const recaptchaRef = useRef<ReCaptchaV2Ref>(null);

  const handleSubmit = async (e) => {
    e.preventDefault();
    const token = await recaptchaRef.current?.execute();
    // Puedes usar el token aquí
    console.log("reCAPTCHA token:", token);
  };

  return (
    <>
      <form onSubmit={handleSubmit}>
        <button type="submit">Submit</button>
      </form>

      <ReCaptchaV2
        ref={recaptchaRef}
        siteKey="YOUR_PRODUCTION_SITE_KEY"
        // onSuccess es opcional
      />
    </>
  );
}

---

🧠 Props

ReCaptchaV2Props

Prop	Type	Required	Default	Description
siteKey	string	✅	–	Your production Google reCAPTCHA v2 site key.
onSuccess	(token: string) => void	❌	–	Callback opcional cuando reCAPTCHA se resuelve exitosamente.
onError	() => void	❌	–	Callback when reCAPTCHA fails to render or complete.
onExpired	() => void	❌	–	Called when the token expires before verification.
badge	"bottomright" | "bottomleft" | "inline"	❌	"bottomright"	Position of the reCAPTCHA badge on screen.
hl	string	❌	–	Language code (e.g., "en", "es") for localization.
isDevelop	boolean	❌	false	Uses Google's default test key if true ("6LeIxAcTAAAA...").
size	"invisible" | "normal" | "compact"	❌	invisible	Size of the recaptcha

---

🧪 Ref Methods

ReCaptchaV2Ref

Method	Type	Description
execute	() => Promise<string>	Ejecuta el reto invisible y retorna el token generado.
reset	() => void	Resetea el widget y limpia el token actual.

---

📌 Examples

🌐 Con idioma personalizado y uso de execute

const recaptchaRef = useRef<ReCaptchaV2Ref>(null);

const handleClick = async () => {
  const token = await recaptchaRef.current?.execute();
  console.log("Token:", token);
};

<ReCaptchaV2 ref={recaptchaRef} siteKey="YOUR_SITE_KEY" hl="es" />;

🧪 Modo desarrollo

const recaptchaRef = useRef<ReCaptchaV2Ref>(null);

const handleClick = async () => {
  const token = await recaptchaRef.current?.execute();
  console.log("Test token:", token);
};

<ReCaptchaV2 isDevelop ref={recaptchaRef} siteKey="will-be-ignored" />;

🧭 Posición personalizada del badge

const recaptchaRef = useRef<ReCaptchaV2Ref>(null);

const handleClick = async () => {
  const token = await recaptchaRef.current?.execute();
  console.log("Token:", token);
};

<ReCaptchaV2 badge="bottomleft" ref={recaptchaRef} siteKey="YOUR_SITE_KEY" />;

---

🧰 Tips

• The reCAPTCHA will not trigger until you call execute() manually.
• Invisible reCAPTCHA es ideal para validaciones no intrusivas antes de enviar acciones sensibles (ej: formularios, comentarios, eliminar).
• Si necesitas retos visibles, cambia el prop size a "normal" o "compact".

---

🏗️ Arquitectura limpia

La librería está estructurada siguiendo Clean Architecture:

• domain: Interfaces y tipos principales.
• application: Hook/caso de uso para el ciclo de vida y callbacks.
• infrastructure: Servicio para cargar y renderizar el widget/script.
• presentation: Componente React que solo orquesta y delega.

Esto permite fácil mantenimiento, testeo y extensión.

---

🧪 Test Key for Local Development

Use this key when testing locally (no need to register it):

siteKey = "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI";

---

📜 License

MIT © Andrés Felipe Hernández Aldana

---

💡 Credits

Built using:

• Google reCAPTCHA v2
• React
• TypeScript