use-captcha-react
Version:
React hook for captcha providers
99 lines (63 loc) • 3.65 kB
Markdown
# use-captcha-react
A generic wrapper for using captcha scripts on the client side in React applications.
[](https://badge.fury.io/js/use-captcha-react)
<p align="center">
<img width="460" height="300" src="https://utfs.io/f/kes5TjpOmvT37Hqz4LTFBjMAYTx2SXPDezZO36Ramg51riod">
</p>
## 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:
```bash
npm i use-captcha-react
```
Or, if you are using pnpm:
```bash
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.
```typescript
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.
```typescript
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.
```typescript
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.
### 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.
Learn more into the [create a provider](https://github.com/GabrielJesusS/use-captcha-react/blob/main/docs/create-a-provider.md) dedicated page!
## 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](https://www.npmjs.com/package/react-google-recaptcha) library created by [Hugo Dozois](https://github.com/dozoisch).
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.
Created by [Gabriel Jesus](https://github.com/GabrielJesusS).