npm package: @pimred/whcaptcha
Description: ```bash npm install --save @pimred/whcaptcha ```
Latest version: 0.5.2

# React Client for WHCaptcha

## Install

```bash
npm install --save @pimred/whcaptcha
```

## Requirements

* **configurationId**: ID of the configuration from initial setup
* **sessionString**: ID that is unique per user and per submission (optional)  
If no sessionString is passed it will be created automatically and stores in the Browser's session storage

## Usage

### Minimal example

```jsx
import { WHCaptcha, useWHCaptcha } from '@pimred/whcaptcha'
import '@pimred/whcaptcha/dist/whcaptcha.css'

const Example = () => {
  const configurationId = 'configuration from initial setup'
  const { checkCaptcha, componentProps } = useWHCaptcha({ configurationId })

  ...

  const onSubmit = async () => {
    const captchaIsCorrect = await checkCaptcha()
    if (captchaIsCorrect) {
      ...
    }
  }
  ...

  return (
    <form>
      ...
      <WHCaptcha {...componentProps} />
      <button onClick={onSubmit} />
    </form>
  )
}
```

### Example with session string

```jsx
import { WHCaptcha, useWHCaptcha } from '@pimred/whcaptcha'
import '@pimred/whcaptcha/dist/whcaptcha.css'

const Example = () => {
  const configurationId = 'configuration from initial setup'
  const sessionString = 'identifier for a user session'
  const { checkCaptcha, componentProps } = useWHCaptcha({ configurationId, sessionString })

  ...

  const onSubmit = async () => {
    const captchaIsCorrect = await checkCaptcha()
    if (captchaIsCorrect) {
      ...
    }
  }
  ...

  return (
    <form>
      ...
      <WHCaptcha {...componentProps} />
      <button onClick={onSubmit} />
    </form>
  )
}
```

### Validation on the server

API endpoint

```js
import { WHCaptchaApi } from '@pimred/whcaptcha'

// API route GET /api/whcaptcha
const handleRequest = async (req, res) => {
  const { solution, sessionString } = req.query
  const isCorrect = WHCaptchaApi.checkCaptcha(process.env.WHCAPTCHA_CONFIGURATION_ID, sessionString, solution)
  return res.json({ isCorrect })
}
```

Frontend

```jsx
import { WHCaptcha, useWHCaptcha } from '@pimred/whcaptcha'
import '@pimred/whcaptcha/dist/whcaptcha.css'

const Example = () => {
  const configurationId = 'configuration from initial setup'
  const { componentProps, getSessionString, getSolution } = useWHCaptcha({ configurationId })

  ...

  const onSubmit = async () => {
    const captchaValidationFromServer = await fetch(`/api/whcaptcha?sessionString=${getSessionString()}&solution=${getSolution()}`).then(response => response.json())
    if (captchaValidationFromServer.isCorrect) {
      ...
    }
  }
  ...

  return (
    <form>
      ...
      <WHCaptcha {...componentProps} />
      <button onClick={onSubmit} />
    </form>
  )
}
```

 ## API

 ### Hook: useWHCaptcha

 ```jsx
  const {
    checkCaptcha,
    loadCaptcha,
    getSessionString,
    getSolution,
    componentProps: {
      texts,
      images,
      clickedImages,
      handleClickOnImage,
      isSolved,
      isSubmitted,
      error
    }} = useWHCaptcha({ configurationId, sessionString })
 ```

The hook returns
* **checkCaptcha**: Function to perform the check of captcha  
Note: when you call **checkCaptcha** and the result is correct you can't call it again with the same challenge. You need to reload the captcha first (with **loadCaptcha**).
* **loadCaptcha**: Function to perform a reload of captcha
* **getSessionString**: Helper function to return the session string if generated by the hook
* **getSolution**: Helper function to return the selected solution
* **componentProps**: Object that should be passed to the **WHCaptcha** component.

```jsx
<WHCaptcha {...componentProps} />
```

### Component: WHCaptcha

![WHCaptcha](whcaptcha.png)

Pass the props from the hook: **componentProps**.

* **height** number in pixel that will be passed to the div on order to prevent a CLS
* **language** language code
* **className** CSS class for the container
* **imageClassName** CSS class for every **image**
* **headlineClassName** CSS class for the **headline**
* **bottomLineClassName** CSS class for the **bottomLine**
* **focusColor** color for the captcha image when it's active