Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/le0developer/react-turnstile
A very simple React library for Cloudflare Turnstile.
https://github.com/le0developer/react-turnstile
cloudflare-turnstile react turnstile
Last synced: 3 days ago
JSON representation
A very simple React library for Cloudflare Turnstile.
- Host: GitHub
- URL: https://github.com/le0developer/react-turnstile
- Owner: Le0Developer
- License: mit
- Created: 2022-09-29T19:36:36.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-24T11:29:29.000Z (about 2 months ago)
- Last Synced: 2024-11-05T13:49:35.587Z (15 days ago)
- Topics: cloudflare-turnstile, react, turnstile
- Language: TypeScript
- Homepage: https://turnstile-demo.pages.dev/
- Size: 103 KB
- Stars: 100
- Watchers: 1
- Forks: 15
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- License: LICENSE
Awesome Lists containing this project
README
# react-turnstile
A very simple React library for [Cloudflare Turnstile](https://challenges.cloudflare.com).
## Installation
```sh
npm i react-turnstile
```
## Usage
```jsx
import Turnstile, { useTurnstile } from "react-turnstile";
// ...
function TurnstileWidget() {
const turnstile = useTurnstile();
return (
{
fetch("/login", {
method: "POST",
body: JSON.stringify({ token }),
}).then((response) => {
if (!response.ok) turnstile.reset();
});
}}
/>
);
}
```
Turnstile tokens expire after 5 minutes, to automatically reset the challenge once they expire,
set the `refreshExpired` prop to `'auto'` or reset the widget yourself using the `onExpire` callback.
### Reducing Layout Shift
The turnstile iframe initially loads as invisible before becoming visible and
expanding to the expected widget size.
This causes Layout Shift and reduces your Cumulative Layout Shift score and UX.
This can be fixed with the `fixedSize={true}` option, which will force the
wrapper div to be the specific size of turnstile.
### Bound Turnstile Object
The Bound Turnstile Object is given as argument to all callbacks and allows you
to call certain `window.turnstile` functions without having to store the `widgetId`
yourself.
```js
function Component() {
return (
{
// before:
window.turnstile.execute(widgetId);
// now:
bound.execute();
}}
/>
);
}
```
## Documentation
Turnstile takes the following arguments:
| name | type | description |
| ----------------- | ------- | ---------------------------------------------------- |
| sitekey | string | sitekey of your website (REQUIRED) |
| action | string | - |
| cData | string | - |
| theme | string | one of "light", "dark", "auto" |
| language | string | override the language used by turnstile |
| tabIndex | number | - |
| responseField | boolean | controls generation of `` element |
| responseFieldName | string | changes the name of `` element |
| size | string | one of "normal", "compact" |
| fixedSize | boolean | fix the size of the `
` to reduce layout shift |
| retry | string | one of "auto", "never" |
| retryInterval | number | interval of retries in ms |
| refreshExpired | string | one of "auto", "manual", "never" |
| appearance | string | one of "always", "execute", "interaction-only" |
| execution | string | one of "render", "execute" |
| id | string | id of the div |
| userRef | Ref | custom react ref for the div |
| className | string | passed to the div |
| style | object | passed to the div |
And the following callbacks:
| name | arguments | description |
| ------------------- | --------------------------- | --------------------------------------------------- |
| onVerify | token | called when challenge is passed |
| onSuccess | token, preClearanceObtained | called when challenge is passed |
| onLoad | widgetId | called when the widget is loaded |
| onError | error | called when an error occurs |
| onExpire | - | called when the token expires |
| onTimeout | token | called when the challenge expires |
| onAfterInteractive | - | called when the challenge becomes interactive |
| onBeforeInteractive | - | called when the challenge no longer is interactive |
| onUnsupported | - | called when the browser is unsupported by Turnstile |
The callbacks also take an additional `BoundTurnstileObject` which exposes
certain functions of `window.turnstile` which are already bound to the
current widget, so you don't need track the `widgetId` yourself.
For more details on what each argument does, see the [Cloudflare Documentation](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#configurations).