google-react-recaptcha-v2/README.md

React component for Google reCAPTCHA

# 🛡️ 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

```bash
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

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

### 2. Add the Component to Your Form

```tsx
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

```tsx
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

```tsx
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

```tsx
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):

```ts
siteKey = "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI";
```

---


## 📜 License

MIT © [Andrés Felipe Hernández Aldana](https://github.com/AndresH11)

---


## 💡 Credits

Built using:

- [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/invisible)
- [React](https://reactjs.org/)
- [TypeScript](https://www.typescriptlang.org/)