Script Options

Configure how Better CAPTCHA loads provider scripts, including manual loading and custom timeouts.

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

Option	Type	Default	Description
`autoLoad`	`boolean`	`true`	Whether to automatically load the provider script
`timeout`	`number`	`15000`	Maximum time (in milliseconds) to wait for script loading
`overrideScriptUrl`	`string`	`undefined`	Override the default script URL with a custom one

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 to add custom attributes to the script tag
You're using a CSP policy that requires specific script handling
You want to optimize script loading with your own strategy

When autoLoad is disabled, ensure the provider script is available globally before the component mounts or before calling render().

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

When using overrideScriptUrl, make sure the custom URL points to a compatible version of the provider script. The URL should be the full path to the script file.

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"
  }}
/>

Script Options

On this page