use-captcha-react

Description

use-captcha-react is a generic wrapper for using captcha scripts on the client side in React applications. It provides a simple and flexible interface to integrate captcha providers, whether pre-configured by the package or custom-built by developers. Perfect for managing captchas consistently and reusable across React projects.

How to Use

Installation

To install the library, use one of the following commands:

npm i use-captcha-react

Or, if you are using pnpm:

pnpm add use-captcha-react

Usage

Use the useCaptcha hook to initialize and interact with the captcha. Pass the provider (e.g., GoogleReCaptchaV2Provider) and the site key to the hook.

const [ref, { executeAsync, getValue }] = useCaptcha(
  GoogleReCaptchaV2Provider,
  siteKey
);

Create a function to handle the form submission. Use executeAsync, for example, to verify the captcha before processing the form.

function handleSubmit(handler: FormEventHandler) {
  return async (event: FormEvent) => {
    event.preventDefault();

    const token = await executeAsync();

    if (token) {
      handler(event);
    }
  };
}

async function handleSuccessSubmit() {
  const token = getValue();
  /* Handle your form submission process here */
}

Attach the ref to an HTML element to display the captcha widget. Wrap your form logic with the handlers.

return (
  <form onSubmit={handleSubmit(handleSuccessSubmit)}>
    <div ref={ref} />
  </form>
);

Core Concepts

useCaptcha Hook

The useCaptcha hook is the main entry point for using captchas with this library. It takes a provider as input and abstracts its initialization and execution methods, offering a more "plug-and-play" experience.

This hook not only simplifies captcha usage but also exposes the provider instance, allowing developers to directly manipulate it or create custom methods if needed.

Provider Class

The provider is a class that defines the captcha to be used. It contains the following properties and methods:

| Method | Description | |----------------|------------------------------------------------------------------| | name | The name of the provider. | | src | The URL from which the captcha script will be loaded. | | options? | The configuration options for the captcha (varies by provider). | | execute | Executes the captcha process. | | reset | Resets the captcha. | | executeAsync | Executes the captcha asynchronously, returning a Promise with the captcha token or null. | | getWidget | Retrieves the widget identifier, if applicable. | | getValue | Gets the current captcha value. | | initialize | Initializes the captcha with the given DOM element. |

These properties and methods allow for a highly flexible implementation, supporting both predefined and custom captcha integrations.

Extending Captcha Functionality

The captcha provider can include additional methods if the developer wants to expose more functionality. While the default interface covers the core methods, you can extend it to suit your specific requirements or to leverage unique features of your chosen captcha provider.

Note

The useCaptcha hook manages scripts on the page to ensure no duplicates are added. However, the code executed by these scripts is not controlled by the hook. This means that elements, attributes, or variables generated by these scripts may be executed multiple times if the script is removed and added back to the page.

Motivation

The use-captcha-react package was designed to simplify captcha integration with React's modern hook standards. It is inspired by the react-google-recaptcha library created by Hugo Dozois.

In addition to its hook-based approach, the generic nature of this wrapper allows developers to integrate various captcha providers in a flexible and configurable manner, all within the same library.