npm package: @pitininja/cap-react-widget
Description: [![npm version](https://badge.fury.io/js/@pitininja%2Fcap-react-widget.svg)](https://badge.fury.io/js/@pitininja%2Fcap-react-widget)
Latest version: 1.3.5

# Cap React Widget

[![npm version](https://badge.fury.io/js/@pitininja%2Fcap-react-widget.svg)](https://badge.fury.io/js/@pitininja%2Fcap-react-widget)

> React wrapper around the [Cap.js](https://capjs.js.org/) widget

## Requirements

- React >= 19

## Install

```shell
npm i @pitininja/cap-react-widget
```

## Usage

### Example

Import the CSS in your entrypoint (most of the time `App.tsx`) :

```tsx
import '@pitininja/cap-react-widget/dist/index.css';
```

Use the widget like this :

```tsx
import { CapWidget } from '@pitininja/cap-react-widget';

const MyComponent = () => {
    return (
        <CapWidget
            endpoint="/api/"
            onSolve={(token) => {
                console.log(`Challenge succeeded, token : ${token}`);
            }}
            onError={() => {
                console.log(`Challenge failed`);
            }}
        />
    );
};
```

### Props

#### Required

| Name            | Type                      |
|-----------------|---------------------------|
| `endpoint`      | `string`                  |
| `onSolve`       | `(token: string) => void` |

#### Optional

| Name                     | Type                                                       |
|--------------------------|------------------------------------------------------------|
| `theme`                  | `'light' \| 'dark'`                                        |
| `workerCount`            | `number`                                                   |
| `onError`                | `(message: string) => void`                                |
| `onProgress`             | `(progress: number) => void`                               |
| `onReset`                | `() => void`                                               |
| `customFetch`            | `(url: string, options?: RequestInit) => Promise<unknown>` |
| `customWaspUrl`          | `string`                                                   |
| `i18nVerifying`          | `string`                                                   |
| `i18nInitial`            | `string`                                                   |
| `i18nSolved`             | `string`                                                   |
| `i18nError`              | `string`                                                   |
| `i18nVerifyAriaLabel`    | `string`                                                   |
| `i18nVerifyingAriaLabel` | `string`                                                   |
| `i18nVerifiedAriaLabel`  | `string`                                                   |
| `i18nErrorAriaLabel`     | `string`                                                   |
| `ref`                    | `Ref<CapWidgetElement>`                                    |

### Trigger events

Use the `ref` to trigger events :

```tsx
import { useRef } from 'react';
import { CapWidget, type CapWidgetElement } from '@pitininja/cap-react-widget';

const MyComponent = () => {
    const widgetRef = useRef<CapWidgetElement | null>(null);
    return (
        <>
            <CapWidget
                ref={widgetRef}
                endpoint="/api/"
                onSolve={(token) => {
                    console.log(`Challenge succeeded, token : ${token}`);
                }}
            />
            <button
                type="button"
                onClick={() => widgetRef.current?.dispatchEvent('reset')}
            >
                Reset
            </button>
        </>
    );
};
```

## Development

1. Run a standalone server :

```shell
docker run -p 3000:3000 -e ADMIN_KEY=xxxxxxxxxxxx --name cap tiago2/cap:latest
```

2. Go to the Cap dashboard and get your key ID

3. Create an environment file :

```shell
cp .env.sample .env
```

4. Set the Cap endpoint in the .env file

5. Run the development app :

```shell
npm run dev
```