Script Options

Overview

Every Better CAPTCHA component accepts a scriptOptions prop to control how provider scripts are loaded. This gives you fine-grained control over script loading behavior, timeouts, and manual script injection.

Configuration Options

Auto Load

Set autoLoad: false if you prefer to inject the provider script yourself. This is useful when:

• You want to load scripts through a custom script loader
• You need full control over where and when the script tag is inserted in the document
• You're using a CSP policy that requires specific script handling that cannot be satisfied by the built-in loader
• You want to optimize script loading with your own strategy

When autoLoad is true (the default), you can still pass nonce, integrity, referrerPolicy, and other script fields through scriptOptions; they are applied to the dynamically created <script> element.

Timeout

Override the default 15-second timeout if you need more time for script loading. This is useful for:

• Slow network connections
• Custom script hosts
• Development environments with slower response times

Override Script URL

Use overrideScriptUrl to load the provider script from a custom URL instead of the default one. This is useful for:

• Using a custom CDN or mirror
• Loading scripts from a self-hosted location
• Bypassing network restrictions
• Testing with different script versions

Script tag attributes

These options only apply when autoLoad is not false. They map to properties or attributes on the <script> element the library appends to document.head.

• nonce: Required by many CSP setups that use script-src 'nonce-…'. Use the same nonce your server emits for other inline or dynamic scripts.
• integrity: Use with a hash from your CSP or supply chain tooling; the URL you load must match the hash.
• crossOrigin: Set CORS mode for the script request (for example "anonymous" when you need CORS-enabled error reporting).
• referrerPolicy: Controls the Referrer-Policy for the script request (browser type: ReferrerPolicy).
• fetchPriority: Optional priority hint ("high", "low", or "auto").
• scriptAttributes: Arbitrary string attributes (for example { "data-captcha-loader": "app" }). Values are passed to setAttribute. Avoid overriding src unless you know the loader URL and your attributes stay consistent.

If you import loadScript from @better-captcha/core directly, pass provider-level options under scriptOptions so they merge with per-call options (for example loadScript(url, { scriptOptions: { nonce }, async: true })).

Usage

import { ReCaptcha } from "@better-captcha/react/provider/recaptcha";

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{ autoLoad: false, timeout: 30000 }}
  onReady={() => console.log("ready")}
/>;

import { component$ } from "@builder.io/qwik";
import { ReCaptcha } from "@better-captcha/qwik/provider/recaptcha";

export default component$(() => (
  <ReCaptcha
    sitekey="your-site-key"
    scriptOptions={{ autoLoad: false, timeout: 30000 }}
  />
));

import { ReCaptcha } from "@better-captcha/solidjs/provider/recaptcha";

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{ autoLoad: false, timeout: 30000 }}
/>;

<template>
  <ReCaptcha
    sitekey="your-site-key"
    :script-options="{ autoLoad: false, timeout: 30000 }"
  />
</template>

<script setup lang="ts">
import { ReCaptcha } from "@better-captcha/vue/provider/recaptcha";
</script>

<script lang="ts">
import ReCaptcha from "@better-captcha/svelte/provider/recaptcha";
</script>

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{ autoLoad: false, timeout: 30000 }}
/>

import "@better-captcha/lit/provider/recaptcha";

const captcha = document.createElement("better-captcha-recaptcha");
captcha.setAttribute("sitekey", "your-site-key");
captcha.scriptOptions = { autoLoad: false, timeout: 30000 };
document.body.appendChild(captcha);

Examples

Increase Timeout

Useful for slower networks or custom CDN configurations:

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{ timeout: 30000 }} // 30 seconds
/>

Manual Script Loading

Load the script yourself and disable auto-loading:

<!-- Add this to your HTML head -->
<script src="https://www.google.com/recaptcha/api.js" async defer></script>

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{ autoLoad: false }}
/>

Custom Script URL

Load the script from a custom URL:

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{
    overrideScriptUrl: "https://custom-cdn.com/recaptcha/api.js"
  }}
/>

Combined Configuration

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{
    autoLoad: false,
    timeout: 30000,
    overrideScriptUrl: "https://custom-cdn.com/recaptcha/api.js"
  }}
/>

CSP nonce on the provider script

Use the nonce your framework or middleware added to the request (example shows a placeholder):

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{
    nonce: cspNonceFromRequest,
    referrerPolicy: "strict-origin-when-cross-origin",
  }}
/>

Extra attributes

<ReCaptcha
  sitekey="your-site-key"
  scriptOptions={{
    scriptAttributes: { "data-app": "checkout" },
  }}
/>