React component for Google reCAPTCHA v2.
npm install --save react-google-recaptcha
All you need to do is sign up for an API key pair. You will need the client key then you can use <ReCAPTCHA />
.
The default usage imports a wrapped component that loads the google recaptcha script asynchronously then instantiates a reCAPTCHA
the user can then interact with.
Code Example:
import ReCAPTCHA from "react-google-recaptcha";
function onChange(value) {
console.log("Captcha value:", value);
}
ReactDOM.render(
<ReCAPTCHA
sitekey="Your client site key"
onChange={onChange}
/>,
document.body
);
Properties used to customise the rendering:
Name | Type | Description |
---|---|---|
asyncScriptOnLoad | func | optional callback when the google recaptcha script has been loaded |
badge | enum |
optional bottomright , bottomleft or inline . Positions reCAPTCHA badge. Only for invisible reCAPTCHA
|
hl | string | optional set the hl parameter, which allows the captcha to be used from different languages, see reCAPTCHA hl |
isolated | bool |
optional For plugin owners to not interfere with existing reCAPTCHA installations on a page. If true, this reCAPTCHA instance will be part of a separate ID space. (default: false )
|
onChange | func | The function to be called when the user successfully completes the captcha |
onErrored | func | optional callback when the challenge errored, most likely due to network issues. |
onExpired | func | optional callback when the challenge is expired and has to be redone by user. By default it will call the onChange with null to signify expired callback. |
sitekey | string | The API client key |
data-action | string | Data-action may only contain only alphanumeric characters, slashes, and underscores. Data-action must not be user-specific. It is important to check the action returned in the verify response. |
size | enum |
optional compact , normal or invisible . This allows you to change the size or do an invisible captcha |
stoken | string | optional set the stoken parameter, which allows the captcha to be used from different domains, see reCAPTCHA secure-token |
tabindex | number |
optional The tabindex on the element (default: 0 )
|
type | enum |
optional image or audio The type of initial captcha (defaults: image )
|
theme | enum |
optional light or dark The theme of the widget (defaults: light ). See example
|
The component instance also has some utility functions that can be called. These can be accessed via ref
.
-
getValue()
returns the value of the captcha field -
getWidgetId()
returns the recaptcha widget Id -
reset()
forces reset. See the JavaScript API doc -
execute()
programmatically invoke the challenge- need to call when using
"invisible"
reCAPTCHA - example below
- need to call when using
-
executeAsync()
programmatically invoke the challenge and return a promise that resolves to the token or errors(if encountered).- alternative approach to
execute()
in combination with theonChange()
prop - example below
- alternative approach to
-
getValue()
after the user completes the reCAPTCHA challenge programmatically get the token response for the reCAPTCHA widget.
Example:
const recaptchaRef = React.createRef();
...
onSubmit = () => {
const recaptchaValue = recaptchaRef.current.getValue();
this.props.onSubmit(recaptchaValue);
}
render() {
return (
<form onSubmit={this.onSubmit} >
<ReCAPTCHA
ref={recaptchaRef}
sitekey="Your client site key"
onChange={onChange}
/>
</form>
)
}
▶ Codesandbox invisible example
See the reCAPTCHA documentation to see how to configure it.
With the invisible option, you need to handle things a bit differently. You will need to call the execute
method yourself.
import ReCAPTCHA from "react-google-recaptcha";
const recaptchaRef = React.createRef();
ReactDOM.render(
<form onSubmit={() => { recaptchaRef.current.execute(); }}>
<ReCAPTCHA
ref={recaptchaRef}
size="invisible"
sitekey="Your client site key"
onChange={onChange}
/>
</form>,
document.body
);
Additionally, you can use the executeAsync
method to use a promise based approach.
import ReCAPTCHA from "react-google-recaptcha";
const ReCAPTCHAForm = (props) => {
const recaptchaRef = React.useRef();
const onSubmitWithReCAPTCHA = async () => {
const token = await recaptchaRef.current.executeAsync();
// apply to form data
}
return (
<form onSubmit={onSubmitWithReCAPTCHA}>
<ReCAPTCHA
ref={recaptchaRef}
size="invisible"
sitekey="Your client site key"
/>
</form>
)
}
ReactDOM.render(
<ReCAPTCHAForm />,
document.body
);
useRecaptchaNet: If google.com is blocked, you can set useRecaptchaNet
to true
so that the component uses recaptcha.net instead.
enterprise: if you want to use Google Enterprise Recaptcha, instead of the free version, set enterprise
to true
.
Example global properties:
window.recaptchaOptions = {
useRecaptchaNet: true,
enterprise: true,
};
window.recaptchaOptions = {
nonce: document.querySelector('meta[name=\'csp-nonce\']').getAttribute('content'),
};
You can also use the barebone components doing the following. Using that component will oblige you to manage the grecaptcha dep and load the script by yourself.
import { ReCAPTCHA } from "react-google-recaptcha";
const grecaptchaObject = window.grecaptcha // You must provide access to the google grecaptcha object.
render(
<ReCAPTCHA
ref={(r) => this.recaptcha = r}
sitekey="Your client site key"
grecaptcha={grecaptchaObject}
/>,
document.body
);
According to the google docs you are allowed to hide the badge as long as you include the reCAPTCHA branding visibly in the user flow. Please include the following text:
This site is protected by reCAPTCHA and the Google
<a href="https://policies.google.com/privacy">Privacy Policy</a> and
<a href="https://policies.google.com/terms">Terms of Service</a> apply.
If you wish to hide the badge you must add:
.grecaptcha-badge { visibility: hidden; }
to your css.