Auto Theme
Automatic theme detection for CAPTCHA providers that don't natively support "auto" theme.
Overview
Better CAPTCHA automatically detects your users' system theme preference and applies it to CAPTCHA providers that don't natively support "auto" theme mode. This ensures a seamless experience across light and dark modes without additional configuration.
How It Works
When you set theme: "auto" in the options, the library:
- Detects the system theme using the
prefers-color-schemeCSS media query - Converts it to either
"light"or"dark" - Passes the resolved theme to the provider
- Automatically updates when the system theme changes
Providers with native auto theme support (Turnstile, Friendly Captcha) pass through the "auto" value directly without conversion.
import { ReCaptcha } from "@better-captcha/react/provider/recaptcha";
<ReCaptcha
sitekey="your-site-key"
options={{ theme: "auto" }} // Automatically detects system theme
/>import { component$ } from "@builder.io/qwik";
import { ReCaptcha } from "@better-captcha/qwik/provider/recaptcha";
export default component$(() => (
<ReCaptcha
sitekey="your-site-key"
options={{ theme: "auto" }} // Automatically detects system theme
/>
));import { ReCaptcha } from "@better-captcha/solidjs/provider/recaptcha";
<ReCaptcha
sitekey="your-site-key"
options={{ theme: "auto" }} // Automatically detects system theme
/><template>
<ReCaptcha
sitekey="your-site-key"
:options="{ theme: 'auto' }" <!-- Automatically detects system theme -->
/>
</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"
options={{ theme: "auto" }} <!-- Automatically detects system theme -->
/>import { ReCaptcha } from "@better-captcha/lit/provider/recaptcha";<recaptcha-captcha sitekey="your-site-key"></recaptcha-captcha>
<script>
const captcha = document.querySelector('recaptcha-captcha');
captcha.options = { theme: 'auto' }; // Automatically detects system theme
</script>Provider Support
| Provider | Native Support | Better CAPTCHA Enhancement | Behavior |
|---|---|---|---|
| Turnstile | ✅ Yes | Not needed | Passes "auto" directly to provider |
| Friendly Captcha | ✅ Yes | Not needed | Passes "auto" directly to provider |
| reCAPTCHA | ❌ No | ✅ Enhanced | Converts to "light" or "dark" |
| hCaptcha | ❌ No | ✅ Enhanced | Converts to "light" or "dark" |
| Private Captcha | ❌ No | ✅ Enhanced | Converts to "light" or "dark" |
| Captcha Fox | ❌ No | ✅ Enhanced | Converts to "light" or "dark" |
| Prosopo | ❌ No | ✅ Enhanced | Converts to "light" or "dark" |
| CapWidget | ❌ No | ✅ Enhanced | Converts to "light" or "dark" |
Benefits
- Seamless User Experience: Automatically matches your site's theme
- No Manual Detection: No need to implement your own theme detection logic
- Reactive Updates: Automatically responds to system theme changes
- Universal API: Use
theme: "auto"across all providers with consistent behavior