Skip to main content
The ReCAPTCHA component accepts various props to customize its appearance and behavior. All props can be passed as standard React component properties.

​
Required Props

​
sitekey
string
required
Your Google reCAPTCHA site key. You can obtain this by signing up for an API key pair.
<ReCAPTCHA sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" />

​
Callback Props

​
onChange
function
Callback function that is called when the user successfully completes the captcha challenge. Receives the captcha token as a parameter.Default: () => {}
function handleChange(token) {
  console.log("Captcha token:", token);
  // Send token to your backend for verification
}

<ReCAPTCHA
  sitekey="your-site-key"
  onChange={handleChange}
/>
​
onExpired
function
Callback function that is called when the captcha challenge expires and needs to be redone by the user. By default, if not provided, it will call onChange with null to signify expiration.
function handleExpired() {
  console.log("Captcha expired, user needs to verify again");
  setError("Please complete the captcha again");
}

<ReCAPTCHA
  sitekey="your-site-key"
  onExpired={handleExpired}
/>
​
onErrored
function
Callback function that is called when the captcha challenge encounters an error, most likely due to network issues.
function handleError() {
  console.error("Captcha failed to load");
  setError("Unable to load captcha. Please check your connection.");
}

<ReCAPTCHA
  sitekey="your-site-key"
  onErrored={handleError}
/>
​
asyncScriptOnLoad
function
Callback function that is called when the Google reCAPTCHA script has been loaded. This is useful for performing actions after the reCAPTCHA API is ready.
This prop is only available when using the default export (wrapper component), not when using the named ReCAPTCHA export.
function handleScriptLoad() {
  console.log("reCAPTCHA script loaded successfully");
}

<ReCAPTCHA
  sitekey="your-site-key"
  asyncScriptOnLoad={handleScriptLoad}
/>

​
Appearance Props

​
theme
enum
The color theme of the widget.Options: "light" | "dark"Default: "light"
<ReCAPTCHA
  sitekey="your-site-key"
  theme="dark"
/>
​
size
enum
The size of the widget. Use "invisible" for invisible reCAPTCHA which requires manual execution.Options: "compact" | "normal" | "invisible"Default: "normal"
// Compact size for mobile
<ReCAPTCHA
  sitekey="your-site-key"
  size="compact"
/>

// Invisible reCAPTCHA
<ReCAPTCHA
  sitekey="your-site-key"
  size="invisible"
  ref={recaptchaRef}
/>
​
badge
enum
Position of the reCAPTCHA badge. Only applies when using size="invisible".Options: "bottomright" | "bottomleft" | "inline"Default: "bottomright"
<ReCAPTCHA
  sitekey="your-site-key"
  size="invisible"
  badge="inline"
/>

​
Interaction Props

​
type
enum
The type of captcha challenge to display initially.Options: "image" | "audio"Default: "image"
<ReCAPTCHA
  sitekey="your-site-key"
  type="audio"
/>
​
tabindex
number
The tabindex attribute for keyboard navigation.Default: 0
<ReCAPTCHA
  sitekey="your-site-key"
  tabindex={1}
/>

​
Localization Props

​
hl
string
Forces the widget to render in a specific language. Uses the hl language code parameter.
// Display in Spanish
<ReCAPTCHA
  sitekey="your-site-key"
  hl="es"
/>

// Display in French
<ReCAPTCHA
  sitekey="your-site-key"
  hl="fr"
/>

​
Advanced Props

​
stoken
string
The secure token parameter that allows the captcha to be used from different domains. See Google’s secure token documentation for more information.
<ReCAPTCHA
  sitekey="your-site-key"
  stoken="your-secure-token"
/>
​
grecaptcha
object
Manually provide the grecaptcha object instead of loading it automatically. This is useful when you want to manage the reCAPTCHA script loading yourself.
When using this prop, you must use the named export { ReCAPTCHA } instead of the default export, as the default export automatically loads the script.
import { ReCAPTCHA } from "react-google-recaptcha";

const grecaptchaObject = window.grecaptcha;

<ReCAPTCHA
  sitekey="your-site-key"
  grecaptcha={grecaptchaObject}
/>
​
isolated
boolean
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
<ReCAPTCHA
  sitekey="your-site-key"
  isolated={true}
/>

​
Additional HTML Attributes

The component also accepts any standard HTML div attributes (className, style, id, etc.) which will be passed through to the container div element. 
<ReCAPTCHA
  sitekey="your-site-key"
  className="my-recaptcha"
  style={{ display: "inline-block" }}
  id="recaptcha-container"
/>

​
Common Prop Combinations

​
Invisible reCAPTCHA with Custom Badge Position

const recaptchaRef = React.useRef();

<form onSubmit={() => recaptchaRef.current.execute()}>
  <ReCAPTCHA
    ref={recaptchaRef}
    sitekey="your-site-key"
    size="invisible"
    badge="inline"
    onChange={handleToken}
  />
  <button type="submit">Submit</button>
</form>

​
Dark Theme with Audio Challenge

<ReCAPTCHA
  sitekey="your-site-key"
  theme="dark"
  type="audio"
  onChange={handleChange}
/>

​
Compact Size with Error Handling

<ReCAPTCHA
  sitekey="your-site-key"
  size="compact"
  onChange={handleChange}
  onExpired={handleExpired}
  onErrored={handleError}
/>

​
Localized reCAPTCHA

<ReCAPTCHA
  sitekey="your-site-key"
  hl="de" // German
  onChange={handleChange}
/>

Build docs developers (and LLMs) love

Get started for freeTalk to us