> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/t49tran/react-google-recaptcha-v3/llms.txt
> Use this file to discover all available pages before exploring further.
# Script Loading Customization
> Learn how to customize the reCAPTCHA script loading behavior with async, defer, nonce, and more
## Overview
The `scriptProps` option gives you fine-grained control over how the Google reCAPTCHA script is loaded and injected into your page. This is essential for:
* Meeting Content Security Policy (CSP) requirements
* Optimizing page load performance
* Controlling script execution timing
* Managing where scripts are inserted in the DOM
## Configuration Options
The `scriptProps` prop accepts an object with the following properties:
Load the reCAPTCHA script asynchronously. The script will download in parallel with page parsing.
Defer script execution until after the page has finished parsing.
Where to inject the script tag in the DOM.
CSP nonce value for inline script execution.
Custom ID for the script element.
Custom name for the global callback function (used with explicit rendering).
## Basic Usage
### Async Loading (Recommended)
Load the reCAPTCHA script asynchronously to avoid blocking page rendering:
```jsx theme={null}
import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
function App() {
return (
);
}
```
### Deferred Loading
Defer script execution until the page is fully parsed:
```jsx theme={null}
```
### Async + Defer (Best for Performance)
Combine both for optimal loading:
```jsx theme={null}
```
Using both `async` and `defer` ensures the script downloads asynchronously and executes after page load, providing the best performance.
## Content Security Policy (CSP)
### Using Nonce
If your site uses CSP with nonce-based script validation:
```jsx theme={null}
function App() {
// Generate or retrieve nonce from your CSP implementation
const nonce = generateNonce(); // Your nonce generation logic
return (
);
}
```
The nonce will be added to the script tag:
```html theme={null}
```
### CSP Headers
Ensure your CSP headers allow reCAPTCHA:
```http theme={null}
Content-Security-Policy:
script-src 'self' 'nonce-YOUR_NONCE' https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/;
frame-src 'self' https://www.google.com/recaptcha/ https://recaptcha.google.com/recaptcha/;
```
reCAPTCHA requires access to both `google.com` and `gstatic.com` domains. Make sure your CSP allows both.
## Script Placement
### Append to Head (Default)
By default, the script is added to ``:
```jsx theme={null}
```
Results in:
```html theme={null}
```
### Append to Body
For better perceived performance, append to end of ``:
```jsx theme={null}
```
Results in:
```html theme={null}
```
Appending to body is recommended when using `async` and `defer` attributes for optimal page load performance.
## Custom Script ID
Use a custom ID if you need to avoid conflicts or have specific tracking requirements:
```jsx theme={null}
```
The library uses this ID for:
* Script element identification (source: `src/utils.ts:148`)
* Preventing duplicate script injection (source: `src/utils.ts:56-57`)
* Cleanup on unmount (source: `src/utils.ts:110-125`)
## Advanced Patterns
### Next.js Integration
Optimized configuration for Next.js applications:
```jsx theme={null}
// pages/_app.js
import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
function MyApp({ Component, pageProps }) {
return (
);
}
export default MyApp;
```
### Server-Side Rendering (SSR)
When using SSR, ensure the script only loads client-side:
```jsx theme={null}
import { useEffect, useState } from 'react';
import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
function App() {
const [isClient, setIsClient] = useState(false);
useEffect(() => {
setIsClient(true);
}, []);
if (!isClient) {
return ;
}
return (
);
}
```
### Dynamic CSP Nonce
Generate and use a unique nonce for each page load:
```jsx theme={null}
import { useMemo } from 'react';
import crypto from 'crypto';
function App() {
const nonce = useMemo(() => {
// Generate cryptographically secure nonce
return crypto.randomBytes(16).toString('base64');
}, []);
// Set CSP header with this nonce (typically done server-side)
useEffect(() => {
const meta = document.createElement('meta');
meta.httpEquiv = 'Content-Security-Policy';
meta.content = `script-src 'self' 'nonce-${nonce}' https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/`;
document.head.appendChild(meta);
return () => document.head.removeChild(meta);
}, [nonce]);
return (
);
}
```
### Custom Load Callback (Explicit Rendering)
When using custom containers, you can customize the callback function name:
```jsx theme={null}
```
This creates:
```javascript theme={null}
window.myCustomRecaptchaCallback = function() {
// reCAPTCHA initialization
};
```
## Performance Optimization
### Lazy Loading Pattern
Only load reCAPTCHA when needed (e.g., when user focuses on a form):
```jsx theme={null}
import { useState } from 'react';
import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
function App() {
const [loadRecaptcha, setLoadRecaptcha] = useState(false);
return (
{loadRecaptcha ? (
) : (
)}
);
}
```
### Preload Hint
Add a preload hint to start downloading the script earlier:
```jsx theme={null}
import { useEffect } from 'react';
function App() {
useEffect(() => {
const link = document.createElement('link');
link.rel = 'preload';
link.as = 'script';
link.href = 'https://www.google.com/recaptcha/api.js';
document.head.appendChild(link);
return () => document.head.removeChild(link);
}, []);
return (
);
}
```
## Complete Example
Here's a production-ready configuration:
```jsx theme={null}
import { useMemo } from 'react';
import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
function App() {
// Stable script props to prevent re-renders
const scriptProps = useMemo(() => ({
async: true,
defer: true,
appendTo: 'body',
nonce: window.__CSP_NONCE__, // Injected by server
id: 'recaptcha-v3-script'
}), []);
return (
My Secure App
);
}
export default App;
```
## Troubleshooting
**Error**: "Refused to load the script because it violates the following Content Security Policy directive"
**Solution**: Update your CSP headers:
```http theme={null}
Content-Security-Policy:
script-src 'self' 'nonce-YOUR_NONCE'
https://www.google.com/recaptcha/
https://www.gstatic.com/recaptcha/;
frame-src 'self'
https://www.google.com/recaptcha/
https://recaptcha.google.com/recaptcha/;
```
**Cause**: Provider is re-rendering with changing `scriptProps`.
**Solution**: Use `useMemo` to keep scriptProps stable:
```jsx theme={null}
const scriptProps = useMemo(() => ({
async: true,
defer: true
}), []); // Empty deps array
```
Source reference: The library detects changes by comparing `JSON.stringify(scriptProps)` (see `src/google-recaptcha-provider.tsx:77`)
**Cause**: Script hasn't finished loading, especially with `async` or `defer`.
**Solution**: Always check if `executeRecaptcha` is available:
```jsx theme={null}
const { executeRecaptcha } = useGoogleReCaptcha();
if (!executeRecaptcha) {
console.log('reCAPTCHA not ready yet');
return;
}
```
**Cause**: Nonce value is empty string or undefined.
**Solution**: Ensure nonce has a truthy value:
```jsx theme={null}
const nonce = getNonce(); // Must return non-empty string
scriptProps={{
nonce: nonce || undefined // Don't pass empty string
}}
```
Source reference: Nonce is only applied if truthy (see `src/utils.ts:172-174`)
**Cause**: Using wrong selector or `appendTo` configuration.
**Solution**:
```jsx theme={null}
// Check where script is
console.log(document.querySelector('#google-recaptcha-v3'));
// Ensure appendTo matches your expectations
scriptProps={{ appendTo: 'body' }} // or 'head'
```
## Best Practices
For best performance, enable both `async` and `defer` to avoid blocking page rendering.
Combine `appendTo: 'body'` with async/defer for optimal perceived performance.
Use `useMemo` for scriptProps to prevent unnecessary script reloads.
Always include both google.com and gstatic.com in your CSP directives.
## Script URL Structure
Understanding how the script URL is constructed (source: `src/utils.ts:166-170`):
```javascript theme={null}
// Standard v3
https://www.google.com/recaptcha/api.js?render=SITE_KEY&hl=LANGUAGE
// Enterprise
https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY&hl=LANGUAGE
// With recaptcha.net
https://www.recaptcha.net/recaptcha/api.js?render=SITE_KEY&hl=LANGUAGE
// Explicit rendering (custom container)
https://www.google.com/recaptcha/api.js?render=explicit&onload=CALLBACK_NAME&hl=LANGUAGE
```
## Combining with Other Features
### Script Props + Enterprise
```jsx theme={null}
```
### Script Props + Custom Container
```jsx theme={null}
```
### All Features Combined
```jsx theme={null}
```
## Resources
* [MDN: async and defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-async)
* [Content Security Policy Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
* [Google reCAPTCHA FAQ](https://developers.google.com/recaptcha/docs/faq)
* [Web Performance Best Practices](https://web.dev/performance/)