{"id":21418615,"url":"https://github.com/siberiacancode/react-google-recaptcha-ultimate","last_synced_at":"2025-07-14T05:31:26.824Z","repository":{"id":182001219,"uuid":"667724813","full_name":"siberiacancode/react-google-recaptcha-ultimate","owner":"siberiacancode","description":"🔑 tool that easily and quickly add Google ReCaptcha for your website or application","archived":true,"fork":false,"pushed_at":"2023-12-13T07:04:28.000Z","size":420,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-01T04:05:39.611Z","etag":null,"topics":["google-recaptcha","react","react-recaptcha","recaptcha-enterprise","recaptcha-v2-checkbox","recaptcha-v2-invisible","recaptcha-v3"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/react-google-recaptcha-ultimate","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/siberiacancode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-18T07:00:19.000Z","updated_at":"2025-03-27T04:54:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"eea772a2-596d-42b4-94de-1b689ce48302","html_url":"https://github.com/siberiacancode/react-google-recaptcha-ultimate","commit_stats":null,"previous_names":["siberiacancode/react-google-recaptcha-ultimate"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/siberiacancode/react-google-recaptcha-ultimate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siberiacancode%2Freact-google-recaptcha-ultimate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siberiacancode%2Freact-google-recaptcha-ultimate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siberiacancode%2Freact-google-recaptcha-ultimate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siberiacancode%2Freact-google-recaptcha-ultimate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/siberiacancode","download_url":"https://codeload.github.com/siberiacancode/react-google-recaptcha-ultimate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siberiacancode%2Freact-google-recaptcha-ultimate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265245952,"owners_count":23734108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-recaptcha","react","react-recaptcha","recaptcha-enterprise","recaptcha-v2-checkbox","recaptcha-v2-invisible","recaptcha-v3"],"created_at":"2024-11-22T19:22:53.250Z","updated_at":"2025-07-14T05:31:26.377Z","avatar_url":"https://github.com/siberiacancode.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔑 React Google ReCaptcha Ultimate\n\ntool that easily and quickly add Google ReCaptcha for your website or application\n\n## Install\n\nInstall with [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)\n\n```bash\n$ npm i react-google-recaptcha-ultimate\n# or\n$ yarn add react-google-recaptcha-ultimate\n```\n\n## 🦉 Philosophy\n\n**🔑 React Google ReCaptcha Ultimate** this is a library that will allow you to easily and quickly add Google ReCaptcha for your website or application. The main difference from other libraries is that all current versions of Google ReCaptcha are supported here.\n\n## Features\n\n- **Support all recaptcha versions** - support v3, v2-checkbox, v2-invisible\n- **Enterprise mode** - support [enterprise](https://cloud.google.com/recaptcha-enterprise/docs/overview)\n- **TypeScript support out of the box** - full typed package\n- **SSR** - package work with server side render\n\n## Usage\n\nInstall **🔑 React Google ReCaptcha Ultimate** with [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)\n\n```bash\n$ npm i react-google-recaptcha-ultimate\n# or\n$ yarn add react-google-recaptcha-ultimate\n```\n\n### V3\n\n[Google ReCaptcha v3](https://developers.google.com/recaptcha/docs/v3) returns a score for each request without user friction. The score is based on interactions with your site and enables you to take an appropriate action for your site.\n\n```typescript jsx\nimport { GoogleReCaptchaProvider } from 'react-google-recaptcha-ultimate';\n\nconst root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);\nroot.render(\n \u003cGoogleReCaptchaProvider\n type=\"v3\"\n siteKey=\"Your recaptcha sitekey\"\n \u003e\n \u003cApp /\u003e\n \u003c/GoogleReCaptchaProvider\u003e\n);\n```\n\n### V2 invisible\n\n[Google ReCaptcha v2 invisible](https://developers.google.com/recaptcha/docs/display) does not require users to solve any puzzles or enter any codes. Instead, it runs in the background and analyzes user behavior on the web page to determine if they are genuine users or potential bots.\n\n```typescript jsx\nimport { GoogleReCaptchaProvider } from 'react-google-recaptcha-ultimate';\n\nconst root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);\nroot.render(\n \u003cGoogleReCaptchaProvider\n type=\"v2-invisible\"\n siteKey=\"Your recaptcha key\"\n \u003e\n \u003cApp /\u003e\n \u003c/GoogleReCaptchaProvider\u003e\n);\n```\n\n### V2 checkbox\n\nWhen a user interacts with the [Google ReCaptcha v2 checkbox](https://developers.google.com/recaptcha/docs/display), advanced algorithms analyze their behavior to distinguish between humans and bots. If the system suspects suspicious activity, additional challenges may be presented, such as image selections or puzzle-solving tasks. \n\n```typescript jsx\nimport { GoogleReCaptchaProvider, GoogleReCaptchaCheckbox } from 'react-google-recaptcha-ultimate';\n\nconst root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);\nroot.render(\n \u003cGoogleReCaptchaProvider\n type=\"v2-checkbox\"\n siteKey=\"Your recaptcha key\"\n \u003e\n \u003cGoogleReCaptchaCheckbox\n onChange={(token) =\u003e {\n console.log(token);\n }}\n /\u003e\n \u003c/GoogleReCaptchaProvider\u003e\n);\n```\n\n### Checkbox component\n\n| **Props** | **Type** | **Default** | **Required?** | **Note** |\n|-----------------|:-----------------------:|------------:|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id | String | | No | Id of component |\n| action | String | | No | An action name is used to describe user-initiated events. [More info](https://cloud.google.com/recaptcha-enterprise/docs/actions) |\n| className | String | | No | Styles for component |\n| container | String or HTMLElement | | No | Container ID where the recaptcha badge will be rendered |\n| callback | (token: string) =\u003e void | | No | The name of your callback function, executed when the user submits a successful response. The g-recaptcha-response token is passed to your callback. |\n| errorCallback | () =\u003e void | | No | The name of your callback function, executed when reCAPTCHA encounters an error (usually network connectivity) and cannot continue until connectivity is restored. If you specify a function here, you are responsible for informing the user that they should retry. |\n| expiredCallback | () =\u003e void | | No | The name of your callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |\n| language | String | | No | optional prop to support different languages that is supported by Google Recaptcha. [See](https://developers.google.com/recaptcha/docs/language) |\n| theme | `dark` or `light` | `light` | No | The color theme of the widget. |\n| size | `compact` or `normal` | `normal` | No | The size of the widget. | |\n| onChange | (token: string) =\u003e void | | No | When called with string (token), it means token retrieved. When called with false as an argument, it means the response expired and the user needs to re-verify. When called with Error, it means an error occurred and the widget cannot continue (usually network disconnection) | |\n\n## Enterprise\n\n[Google ReCaptcha Enterprise](https://cloud.google.com/recaptcha-enterprise/docs/overview) is built on the existing reCAPTCHA API and it uses advanced risk analysis techniques to distinguish between humans and bots.\nIn order to enable enterprise mode, you need to set the flag `isEnterprise` in `GoogleReCaptchaProvider`. Also in this mode you can pass specials `actions`.\n\n### Examples\n\n#### v2 checkbox\n\n```typescript jsx\nimport { GoogleReCaptchaProvider, GoogleReCaptchaCheckbox } from 'react-google-recaptcha-ultimate';\n\nconst root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);\nroot.render(\n \u003cGoogleReCaptchaProvider\n type=\"v2-checkbox\"\n siteKey=\"Your recaptcha key\"\n isEnterprise\n \u003e\n \u003cGoogleReCaptchaCheckbox\n action=\"Your action name\"\n onChange={(token: string) =\u003e {\n console.log(token);\n }}\n /\u003e\n \u003c/GoogleReCaptchaProvider\u003e\n);\n```\n#### v3 or v2 invisible\n\n```typescript jsx\nimport { GoogleReCaptchaProvider } from 'react-google-recaptcha-ultimate';\n\nconst root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);\nroot.render(\n \u003cGoogleReCaptchaProvider\n type=\"Your type of recaptcha\"\n siteKey=\"Your recaptcha key\"\n isEnterprise\n \u003e\n \u003cApp /\u003e\n \u003c/GoogleReCaptchaProvider\u003e\n);\n```\n\n## API\n\n### GoogleReCaptchaProvider\n\n`react-google-recaptcha-ultimate` provides a `GoogleReCaptchaProvider` provider component that should be used to wrap around your components.\n\n`GoogleReCaptchaProvider`'s responsibility is to load the necessary reCaptcha script and provide access to reCaptcha to the rest of your application.\n\nUsually, your application only needs one provider. You should place it as high as possible in your React tree. It's to make sure you only have one instance of Google Recaptcha per page, and it doesn't reload unnecessarily when your components re-rendered.\n\nSame thing applied when you use this library with framework such as Next.js or React Router and only want to include the script on a single page. Try to make sure you only have one instance of the provider on a React tree and to place it as high (on the tree) as possible.\n\n#### GoogleReCaptchaProvider for v3 and v2-invisible \n\nAll the props that can be passed in provider for v2-invisible and v3:\n\n| **Props** | **Type** | **Default** | **Required** | **Note** |\n|--------------------------|:-----------------------------------------------------:|---------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| type | `v3` or `v2-invisible` | | Yes | Your recaptcha version |\n| siteKey | String | | Yes | Your recaptcha key, get one from [here](https://www.google.com/recaptcha/admin) |\n| language | String | | No | Optional prop to support different [languages](https://developers.google.com/recaptcha/docs/language) that is supported by Google Recaptcha |\n| isEnterprise | Boolean | | No | When you enable to use the enterprise version, **you must create new keys**. These keys will replace any Site Keys you created in reCAPTCHA. Check the [migration guide](https://cloud.google.com/recaptcha-enterprise/docs/migrate-recaptcha). |\n| onLoad | () =\u003e void | | No | Callback function to load reCAPTCHA |\n| onError | () =\u003e void | | No | Callback function to error reCAPTCHA |\n| host | `recaptcha.net` or `google.com` | | No | Load script from `recaptcha.net` or `google.com` |\n| scriptProps | Object | | No | All props used by `\u003cscript\u003e` tag |\n| explicit.container | String or HTMLElement | | No | Container ID where the recaptcha badge will be rendered |\n| explicit.tabIndex | Number | 0 | No | The tabindex of the widget and challenge. If other elements in your page use tabindex, it should be set to make user navigation easier. |\n| explicit.inherit | Boolean | | No | Use existing data-* attributes on the element if the corresponding parameter is not specified. The parameters will take precedence over the attributes. |\n| explicit.callback | (token: string) =\u003e void | | No | The name of your callback function, executed when the user submits a successful response. The g-recaptcha-response token is passed to your callback. |\n| explicit.errorCallback | () =\u003e void | | No | The name of your callback function, executed when reCAPTCHA encounters an error (usually network connectivity) and cannot continue until connectivity is restored. If you specify a function here, you are responsible for informing the user that they should retry. |\n| explicit.expiredCallback | () =\u003e void | | No | The name of your callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |\n| explicit.badge | `inline` or `bottomleft` or `bottomright` or `hidden` | `bottomright` | No | Reposition the reCAPTCHA badge. |\n\n#### GoogleReCaptchaProvider for v2-checkbox\n\nAll the props that can be passed in provider for v2-checkbox. We also recommend using the checkbox component rather than explicitly loading the recaptcha checkbox.\n\n| **Props** | **Type** | **Default** | **Required** | **Note** |\n|--------------------------|:-------------------------------:|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| type | `v2-checkbox` | | Yes | Your recaptcha version |\n| siteKey | String | | Yes | Your recaptcha key, get one from [here](https://www.google.com/recaptcha/admin) |\n| language | String | | No | Optional prop to support different [languages](https://developers.google.com/recaptcha/docs/language) that is supported by Google Recaptcha |\n| isEnterprise | Boolean | | No | When you enable to use the enterprise version, **you must create new keys**. These keys will replace any Site Keys you created in reCAPTCHA. Check the [migration guide](https://cloud.google.com/recaptcha-enterprise/docs/migrate-recaptcha). |\n| onLoad | () =\u003e void | | No | Callback function to load reCAPTCHA |\n| onError | () =\u003e void | | No | Callback function to error reCAPTCHA |\n| host | `recaptcha.net` or `google.com` | `google.com` | No | Load script from `recaptcha.net` or `google.com` |\n| scriptProps | Object | | No | All props used by `\u003cscript\u003e` tag |\n| explicit.container | String or HTMLElement | | No | Container ID where the recaptcha badge will be rendered |\n| explicit.tabIndex | Number | 0 | No | The tabindex of the widget and challenge. If other elements in your page use tabindex, it should be set to make user navigation easier. |\n| explicit.inherit | Boolean | | No | Use existing data-* attributes on the element if the corresponding parameter is not specified. The parameters will take precedence over the attributes. |\n| explicit.callback | () =\u003e void | | No | The name of your callback function, executed when the user submits a successful response. The g-recaptcha-response token is passed to your callback. |\n| explicit.errorCallback | () =\u003e void | | No | The name of your callback function, executed when reCAPTCHA encounters an error (usually network connectivity) and cannot continue until connectivity is restored. If you specify a function here, you are responsible for informing the user that they should retry. |\n| explicit.expiredCallback | () =\u003e void | | No | The name of your callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |\n| explicit.action | String | | No | An action name is used to describe user-initiated events corresponding |\n| explicit.theme | `dark` or `light` | `light` | No | The color theme of the widget. Depends on type of reCaptcha |\n| explicit.size | `compact` or `normal` | `normal` | No | The size of the widget. Depends on type of reCaptcha |\n\n### Checkbox component\n\n| **Props** | **Type** | **Default** | **Required?** | **Note** |\n|-----------------|:-----------------------:|------------:|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id | String | | No | Id of component |\n| action | String | | No | An action name is used to describe user-initiated events. [More info](https://cloud.google.com/recaptcha-enterprise/docs/actions) |\n| className | String | | No | Styles for component |\n| container | String or HTMLElement | | No | Container ID where the recaptcha badge will be rendered |\n| callback | () =\u003e void | | No | The name of your callback function, executed when the user submits a successful response. The g-recaptcha-response token is passed to your callback. |\n| errorCallback | () =\u003e void | | No | The name of your callback function, executed when reCAPTCHA encounters an error (usually network connectivity) and cannot continue until connectivity is restored. If you specify a function here, you are responsible for informing the user that they should retry. |\n| expiredCallback | () =\u003e void | | No | The name of your callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |\n| language | String | | No | optional prop to support different languages that is supported by Google Recaptcha. [See](https://developers.google.com/recaptcha/docs/language) |\n| theme | `dark` or `light` | `light` | No | The color theme of the widget. |\n| size | `compact` or `normal` | `normal` | No | The size of the widget. | |\n| onChange | (token: string) =\u003e void | | No | When called with string (token), it means token retrieved. When called with false as an argument, it means the response expired and the user needs to re-verify. When called with Error, it means an error occurred and the widget cannot continue (usually network disconnection) | |\n\n### useGoogleReCaptcha hook\n\nIf you prefer a React Hook approach, you can choose to use the custom hook `useGoogleReCaptcha`.\nWe recommend using this hook for v2 invisible and v3 to trigger recaptcha execution.\n\nThe `executeV3` and `executeV2Invisible` function returned from the hook can be undefined when the recaptcha script has not been successfully loaded.\n\n```typescript jsx\nimport { GoogleReCaptchaProvider, useGoogleReCaptcha } from 'react-google-recaptcha-ultimate';\n\nconst App = () =\u003e {\n const { executeV3 } = useGoogleReCaptcha();\n\n // Create an event handler so you can call the verification on button click event or form submit\n const handleReCaptchaVerify = useCallback(async () =\u003e {\n if (!executeV3) {\n console.log('Execute recaptcha not available');\n return;\n }\n\n const token = await executeV3();\n }, [executeV3]);\n\n // You can use useEffect to trigger the verification as soon as the component being loaded\n useEffect(() =\u003e {\n handleReCaptchaVerify();\n }, [handleReCaptchaVerify]);\n\n return \u003cbutton onClick={handleReCaptchaVerify}\u003everify\u003c/button\u003e;\n};\n\nconst root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);\nroot.render(\n \u003cGoogleReCaptchaProvider siteKey=\"Your recaptcha key\"\u003e\n \u003cApp /\u003e\n \u003c/GoogleReCaptchaProvider\u003e\n);\n```\n\n### withGoogleReCaptcha HOC\n\n`withGoogleReCaptcha` is a HOC (higher order component) that can be used to integrate reCaptcha validation with your component and trigger the validation programmatically. It injects the wrapped component with `googleReCaptcha` object.\n\nThe object contains the `executeV3` and `executeV2Invisible` function that can be called to validate the user action.\n\nYou are recommended to use the custom hook `useGoogleReCaptcha` over the HOC whenever you can. The HOC can be removed in future version.\n\n```typescript jsx\nimport {\n GoogleReCaptchaProvider,\n withGoogleReCaptcha,\n WithGoogleReCaptchaParams\n} from 'react-google-recaptcha-ultimate';\n\nconst App = (props) =\u003e {\n // Create an event handler so you can call the verification on button click event or form submit\n const handleReCaptchaVerify = useCallback(async () =\u003e {\n if (!props.executeV3) {\n console.log('Execute recaptcha not available');\n return;\n }\n\n const token = await props.executeV3();\n }, [props.executeV3]);\n\n // You can use useEffect to trigger the verification as soon as the component being loaded\n useEffect(() =\u003e {\n handleReCaptchaVerify();\n }, [handleReCaptchaVerify]);\n\n return \u003cbutton onClick={handleReCaptchaVerify}\u003everify\u003c/button\u003e;\n};\n\nexport const WithGoogleRecaptchaApp = withGoogleReCaptcha(App);\n\nconst root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);\nroot.render(\n \u003cGoogleReCaptchaProvider siteKey=\"Your recaptcha key\"\u003e\n \u003cWithGoogleRecaptchaApp /\u003e\n \u003c/GoogleReCaptchaProvider\u003e\n);\n```\n\n### generateGoogleReCaptchaScriptSrc\n\nThe function `generateGoogleReCaptchaScriptSrc` function may be needed for applications with ssr to get a link for the recaptcha script and load it before rendering the UI.\n\n| **Parameters** | **Type** | **Required** | **Note** |\n|-----------------|:-------------------------------------------:|--------------|----------------------------------------------------------------------------------------------|\n| host | `recaptcha.net` or `google.com` | No | Load script from `recaptcha.net` or `google.com` |\n| isEnterprise | Boolean | Yes | |\n| render | String | Yes | siteKey of reCaptcha |\n| hl | String | No | Prop to support different languages that is supported by Google Recaptcha |\n| badge | `inline` or `bottomleft` or `bottomright` | No | Reposition the reCAPTCHA badge. Depends on type of reCaptcha. If not provide badge is hidden |\n\n### generateGoogleReCaptchaHiddenBadgeStyles\n\nThe function `generateGoogleReCaptchaHiddenBadgeStyles` function returns [hidden styles](https://developers.google.com/recaptcha/docs/faq) for Google ReCaptcha badge.\n\n## ✨ Contributors\n\n\u003ctable\u003e\n \u003ctr\u003e\n \u003ctd align=\"center\" style=\"word-wrap: break-word; width: 100; height: 100\"\u003e\n \u003ca href=\"https://github.com/debabin\"\u003e\n \u003cimg src=\"https://avatars.githubusercontent.com/u/45297354?v=4\"\n width=\"100;\" \n alt=\"debabin\" /\u003e\n \u003cbr /\u003e\n \u003csub style=\"font-size:13px\"\u003e\u003cb\u003e☄️ debabin\u003c/b\u003e\u003c/sub\u003e\n \u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"center\" style=\"word-wrap: break-word; width: 100.0; height: 100.0\"\u003e\n \u003ca href=\"https://github.com/anv296\"\u003e\n \u003cimg src=\"https://avatars.githubusercontent.com/u/39154399?s=400\u0026u=7c4fcc6d120f4b13ccbd03a9a384622b6523c376\u0026v=4\"\n width=\"100;\" \n alt=\"anv296\" /\u003e\n \u003cbr /\u003e\n \u003csub style=\"font-size:13px\"\u003e\u003cb\u003e🎱️ anv296\u003c/b\u003e\u003c/sub\u003e\n \u003c/a\u003e\n \u003c/td\u003e\n \u003c/tr\u003e\n\u003c/table\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiberiacancode%2Freact-google-recaptcha-ultimate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiberiacancode%2Freact-google-recaptcha-ultimate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiberiacancode%2Freact-google-recaptcha-ultimate/lists"}