# facaptcha
> React CAPTCHA, but it's fun
Latest version **1.2.1** (published 2024-05-25) · MIT license · 0 weekly downloads
## Install
```sh
npm install facaptcha
pnpm add facaptcha
yarn add facaptcha
bun add facaptcha
```
## Health
**Score 30/100 (F)** — status: abandoned.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.2.1 |
| Published | 2024-05-25 |
| First published | 2022-07-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 103.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Dylan Blair |
| Maintainers | dylandbl |
| Keywords | react, react-component, captcha, react-captcha, scambaiting, scam-baiting |
## Links
- npm: https://www.npmjs.com/package/facaptcha
- Repository: https://github.com/dylandbl/faCAPTCHA
- Homepage: https://dylandbl.github.io/faCAPTCHA
- Issues: https://github.com/dylandbl/faCAPTCHA/issues
- npm.io page: https://npm.io/package/facaptcha
## Dependencies (2)
- [@emotion/react](https://npm.io/package/@emotion/react.md) ^11.11.4
- [@emotion/styled](https://npm.io/package/@emotion/styled.md) ^11.10.0
## Alternatives
- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads
## Recent versions
- 1.2.1 (latest) — 2024-05-25
- 1.2.0 — 2023-12-18
- 1.1.2 — 2022-07-09
- 1.1.1 — 2022-07-07
- 1.1.0 — 2022-07-06
- 1.0.0 — 2022-07-04
## README
# faCAPTCHA
👉 **Try it out: [dylandbl.github.io/faCAPTCHA](https://dylandbl.github.io/faCAPTCHA/)**
[**fey**-**kap**-ch*uh*]
A functional, configurable, and *accessible* frontend CAPTCHA for React. The name is a portmanteau of 'fake' and 'CAPTCHA', and was initially an exploration in bad UX, but through development, it became a real and functional CAPTCHA with accessibility features not found in other popular CAPTCHAs. Just be sure to change the [`helpText`](#helptext-default-value).
faCAPTCHA was inspired by scambaiter [Kitboga](https://www.youtube.com/c/KitbogaShow), who uses fake websites or programs to frustrate and waste the time of scammers.
## Installation
```sh
yarn add facaptcha
```
or
```sh
npm install facaptcha
```
# API
'⚠️' denotes required props.
| ⚠️ | Property | Type | Default value | Description |
| --- | --------------------------------- | --------------------------------- | ---------------- | ------------- |
| | `allowRetry` | `boolean` | `false` | Allows the user to retry the CAPTCHA after verification is complete. |
| | [`captchaTopics`](#captchatopics) | `string[]` | [See here](https://github.com/dylandbl/faCAPTCHA/blob/main/src/lib/utils/stringsToFind.ts) | Topics displayed at the top of the CAPTCHA. Does not work with `headerText`. |
| | `cellsWide` | `number` | `4` | Number of cells in each row. |
| | `cellsTall` | `number` | `cellsWide` | Number of cells in each column. |
| | `disabled` | `boolean` | `false` | Disables the CAPTCHA, preventing users from attempting verification. `disabled` is `true` if the user exceeds `maxAttempts`. |
| ⚠️ | [`imgTopicUrls`](#imgtopicurls) | [`ImgTopicType[]`](#imgtopictype) | - | Array of image URLs with associated topic tags. |
| | `headerText` | `string` | [See here](#headertext-default-value) | Used in place of the CAPTCHA header text. Overrides `captchaTopic`. |
| | `helpText` | `string` | [See here](#helptext-default-value) | Used in place of the default help text, shown when the '?' icon is clicked. |
| | `helpButtonAriaLabel` | `string` | `"Help"` | Used as both the `title` and `aria-label` for the '?' icon button. |
| | `maxAttempts` | `number` | `minAttempts + 7` | Maximum number of attempts. If exceeded, `disabled` is set to `true` and `onMaxAttempts` is called. |
| | `minAttempts` | `number` | `1` | Minimum number of required attempts, regardless of whether the attempts are correct or not. |
| | `notARobotText` | `string` | `"I'm not a robot"` | Used in place of the "I'm not a robot" text. |
| | `onClickCheckbox` | `() => void` | - | Called on clicking the checkbox. Does not execute if the CAPTCHA popup is open. |
| | `onClickVerify` | `() => void` | - | Called on clicking the 'Verify' button. |
| | `onMaxAttempts` | `() => void` | - | Called when `maxAttempts` is exceeded. |
| | `onRefresh` | `() => void` | - | Called on clicking the refresh icon. |
| | `refreshButtonAriaLabel` | `string` | `"Try a new challenge"` | Used as both the `title` and `aria-label` for the refresh icon button. |
| ⚠️ | `onVerificationComplete` | `() => void` | - | Called on successful verification completion. |
| | [`simulateSlow`](#simulateslow) | `0 - 3` | `1` | Simulates a slow internet connection speed. |
| | `uncloseable` | `boolean` | `false` | Prevents the CAPTCHA from being closed until verification is complete. |
| | `verifyText` | `string` | `"verify"` | Text for the 'Verify' button. |
## `captchaTopics`
An array of case-sensitive topics, from which one item will be randomly selected. The topic appears in the header of the CAPTCHA and it is the phrase or word that the image tags will be compared to. If not defined, a pseudorandomly selected [default value](https://github.com/dylandbl/faCAPTCHA/blob/main/src/lib/utils/stringsToFind.ts) will be used.
## `imgTopicUrls`
Topic tags are case-sensitive and compared to the topic selected from `captchaTopics`. The images will be displayed in order. If there are fewer images than cells, the images will repeat.
### `ImgTopicType`
```TS
type ImgTopicType = {
url: string;
topics: string[];
}
```
### Example
```TS
const ExampleImages: ImgTopicType[] = [
{
url: "https://upload.wikimedia.org/wikipedia/commons/b/b0/Canthigaster_valentini_1.jpg",
topics: ["pufferfish", "fish", "Canthigaster valentini"]
},
{
url: "https://upload.wikimedia.org/wikipedia/commons/1/11/Joseph_Grimaldi.jpg",
topics: ["clown"]
}
]
```
## `headerText` default value
> Select all squares with
> `${captchaTopic}`
> If there are none, click `${verifyText}`
## `helpText` default value
> Click on the images that correspond with the given prompt. Once you've selected all applicable images, click '`${verifyText}`'. If you make multiple wrong attempts in a row, you will be barred from accessing the site. The number of wrong attempts permitted depends on your browsing behaviour. If you complete an entire row, column, or diagonal, you have a bingo. Shout 'bingo' into your microphone to access the site.
## `simulateSlow`
Simulates a slow connection speed. A value of `0` will not create artificial load times. A value of `1` or greater will render load screens between CAPTCHA attempts and on clicking the component's refresh icon. The load time is randomly generated based on the value given, with higher values generating higher average load times.
---
_Source: https://npm.io/package/facaptcha · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._