@captigo/vue

@captigo/vue

Vue 3 composables and components for Captigo.

Swap providers without changing your component tree — use @captigo/turnstile, @captigo/hcaptcha, or @captigo/recaptcha.

Installation

npm install @captigo/vue @captigo/turnstile

@captigo/core is installed transitively via the adapter. Peer dependency: vue ≥ 3.3.

Quick start

Managed widget (visible checkbox)

The most common case. The widget renders automatically; you read the token reactively.

<script setup lang="ts">
import { turnstile } from "@captigo/turnstile";
import { Captcha } from "@captigo/vue";

// Create the adapter once — outside the component or via computed() to
// avoid unnecessary widget remounts on every reactive update.
const adapter = turnstile({ siteKey: "0x4AAAAAAAxxx" });

function onToken(token) {
  // Forward token.value to your server for verification.
  console.log(token.value);
}
</script>

<template>
  <form @submit.prevent="submitForm">
    <Captcha :adapter="adapter" @success="onToken" />
    <button type="submit">Submit</button>
  </form>
</template>

Invisible widget (interactive / execute on submit)

For invisible Turnstile or invisible hCaptcha, call execute() on form submit to trigger the challenge imperatively.

<script setup lang="ts">
import { ref } from "vue";
import { turnstile } from "@captigo/turnstile";
import { Captcha } from "@captigo/vue";
import type { CaptchaInstance } from "@captigo/vue";

const adapter = turnstile({
  siteKey: "0x4AAAAAAAxxx",
  execution: "execute", // invisible mode
});

const captchaRef = ref<CaptchaInstance>();

async function handleSubmit() {
  const token = await captchaRef.value!.execute("login");
  await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ token: token.value }),
  });
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <Captcha ref="captchaRef" :adapter="adapter" />
    <button type="submit">Log in</button>
  </form>
</template>

useCaptcha composable

For when you need lower-level control or want to integrate with your own markup.

<script setup lang="ts">
import { turnstile } from "@captigo/turnstile";
import { useCaptcha } from "@captigo/vue";

const adapter = turnstile({ siteKey: "0x4AAAAAAAxxx" });

const { containerRef, token, execute, reset } = useCaptcha(adapter, {
  onSuccess: (t) => console.log("solved:", t.value),
  onExpire: () => console.log("token expired"),
  onError: (err) => console.error("widget error:", err),
});
</script>

<template>
  <div>
    <!-- Attach containerRef to the element that should host the widget. -->
    <div :ref="containerRef" class="my-captcha" />

    <!-- token is reactive — use it directly in templates or computed(). -->
    <p v-if="token">Token ready: {{ token.value }}</p>

    <button @click="execute('checkout')">Verify</button>
    <button @click="reset">Reset</button>
  </div>
</template>

Reactive adapter

useCaptcha accepts a plain value, a Ref, or a getter function for the adapter. Changing the adapter destroys the old widget and mounts a new one automatically.

const selectedProvider = ref<"turnstile" | "hcaptcha">("turnstile");

const adapter = computed(() =>
  selectedProvider.value === "turnstile"
    ? turnstile({ siteKey: "..." })
    : hcaptcha({ siteKey: "..." }),
);

const { containerRef, token, execute } = useCaptcha(adapter);

Server-side verification

Never trust tokens on the client. Validate them on your server before acting on them.

// server.ts (Node.js / edge)
import { verifyToken } from "@captigo/turnstile";

const result = await verifyToken(token, process.env.TURNSTILE_SECRET_KEY!);

if (!result.success) {
  throw new Error("CAPTCHA verification failed");
}

See each provider package (@captigo/turnstile, @captigo/hcaptcha, @captigo/recaptcha) for provider-specific verification functions and options.

API reference

<Captcha> component

Prop	Type	Required	Description
adapter	CaptchaAdapter	Yes	Provider adapter (e.g. from @captigo/turnstile)
onSuccess	(token: CaptchaToken) => void	No	Called when a token is produced
onError	(error: CaptchaError) => void	No	Called on an unrecoverable widget error
onExpire	() => void	No	Called when the current token expires

Extra attributes (id, class, style, etc.) fall through to the underlying container <div> automatically.

CaptchaInstance (accessed via template ref):

Method	Description
execute(action?)	Trigger the challenge. Returns Promise<CaptchaToken>.
reset()	Reset the widget to its initial unsolved state.
getToken()	Returns the current CaptchaToken or null.

useCaptcha(adapter, options?)

Parameter	Type	Description
adapter	MaybeRefOrGetter<CaptchaAdapter>	Provider adapter — can be a plain value, Ref, or getter
options.onSuccess	(token) => void	Success callback
options.onError	(error) => void	Error callback
options.onExpire	() => void	Expiry callback

Returns { containerRef, token, execute, reset }.

Return	Type	Description
containerRef	Ref<HTMLDivElement | null>	Bind to the widget container element
token	Ref<CaptchaToken | null>	The current token, reactive
execute	(action?) => Promise<CaptchaToken>	Trigger the challenge
reset	() => void	Reset and clear token

Notes

Adapter identity and remounts

The widget is remounted when the resolved adapter value changes. If you construct the adapter inside a computed() that re-runs frequently, the widget will remount each time. Keep adapters stable:

// Good — created once
const adapter = turnstile({ siteKey: "..." });

// Fine — computed with stable inputs
const adapter = computed(() => turnstile({ siteKey: props.siteKey }));

// Avoid — new object on every reactive update
const adapter = turnstile({ siteKey: reactiveValue.value }); // inside setup()

Passive providers (reCAPTCHA v3)

Score-based providers don't render a visible widget. The <Captcha> component still mounts an empty container; the adapter uses it to initialize. You can hide it with CSS or use useCaptcha and skip rendering containerRef entirely (call execute() to get the token on demand).

Vue Strict Mode

@captigo/vue is compatible with Vue's production build. No special handling is needed for development strict mode since Vue 3 does not remount components the way React Strict Mode does.

Documentation

• Getting started
• Framework integrations
• Server-side verification

@captigo/turnstile · Repository · Issues