Merge pull request #46 from marsidev/feature/widget-loading-callback

feat: Add `onWidgetLoad` callback

Author: marsidev

demos/nextjs/.node-version

@@ -0,0 +1 @@
+v20.10.0

docs/props.mdx

@@ -11,6 +11,7 @@ These are the props you can pass to the `Turnstile` component.
 | `siteKey`       | string   | Your sitekey key, get one from [here](https://developers.cloudflare.com/turnstile/get-started/).                                                                                                                                                                                                                                       | ✅            |
 | ``options``     | object   | Widget render options. More info about this options [below](/props#options-prop).                                                                                                                                                                                                                                                      |              |
 | `scriptOptions` | object   | You can customize the injected `script` tag with this prop. It allows you to add `'async'`, `'defer'`, `'nonce'` attributes to the script tag. You can also control whether the injected script will be added to the document body or head with `appendTo` attribute. More info about this options [below](/props#scriptoptions-prop). |              |
+| `onWidgetLoad`     | function | Callback invoked when the widget is loaded or reloaded (e.g. after a reset).                                                                                                                                                                                                                     |              |
 | `onSuccess`     | function | Callback invoked upon success of the challenge. The callback is passed a token that can be validated.                                                                                                                                                                                                                          |              |
 | `onExpire`      | function | Callback invoked when a challenge expires. Read the [Cloudflare docs](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#refreshing-a-widget) for more info about handling expired widgets.                                                                                                        |              |
 | `onError`         | function | Callback invoked when there is an error (e.g. network error or the challenge failed). Refer to [Client-side errors](https://developers.cloudflare.com/turnstile/reference/client-side-errors).                                                                                                                                                                                                                                                                                |              |

packages/lib/src/lib.tsx

@@ -17,6 +17,7 @@ export const Turnstile = forwardRef<TurnstileInstance | undefined, TurnstileProp
 		scriptOptions,
 		options = {},
 		siteKey,
+		onWidgetLoad,
 		onSuccess,
 		onExpire,
 		onError,
@@ -244,10 +245,12 @@ export const Turnstile = forwardRef<TurnstileInstance | undefined, TurnstileProp
 		if (!widgetId) return
 		if (!checkElementExistence(widgetId)) return
 
+		onWidgetLoad?.(widgetId)
+
 		return () => {
 			window.turnstile!.remove(widgetId)
 		}
-	}, [widgetId])
+	}, [widgetId, onWidgetLoad])
 
 	useEffect(() => {
 		setContainerStyle(

packages/lib/src/types.ts

@@ -299,6 +299,11 @@ interface TurnstileProps extends React.HTMLAttributes<HTMLDivElement> {
 	 */
 	siteKey: RenderOptions['sitekey']
 
+	/**
+	 * Callback invoked when the widget is loaded or reloaded (e.g. after a reset).
+	 */
+	onWidgetLoad?: (widgetID: string) => void
+
 	/**
 	 * Callback invoked upon success of the challenge. The callback is passed a token that can be validated.
 	 * @param token - Token response.