React / Next.js / Gatsby

Install and use the @myrasec/eu-captcha package to embed EU CAPTCHA in your React application.

Package	Version
@myrasec/eu-captcha	1.0.0

Server-side verification is identical regardless of frontend framework — see Server-Side Verification.

---

Installation

npm i @myrasec/eu-captcha

Basic usage

import { EuCaptcha, isEuCaptchaDone } from "@myrasec/eu-captcha";

const captchaSitekey = "EUCAPTCHA_SITE_KEY";

export function ContactForm() {
  return (
    <form onSubmit={handleSubmit}>
      {/* your fields */}
      <EuCaptcha sitekey={captchaSitekey} />
      <button type="submit">Submit</button>
    </form>
  );
}

Props

Prop	Type	Default	Description
sitekey	string	—	Your public sitekey (required)
theme	string	"light"	Visual theme: "light" or "dark"
width	number	330	Widget width in pixels
height	number	100	Widget height in pixels
widgetId	string	—	Custom widget ID. If omitted, an ID is auto-generated. Needed when calling euCaptcha.execute().
autostart	boolean	true	Start the challenge automatically on mount. Set to false to defer until euCaptcha.execute(widgetId) is called.
onComplete	(token: string) => void	—	Called with the encoded token when the challenge completes.
onExpired	() => void	—	Called when the token expires (60 minutes after completion).
onError	() => void	—	Called when the challenge fails due to a network or server error.

Checking completion before submit

The challenge runs asynchronously. Call isEuCaptchaDone() in your submit handler to confirm it has finished before sending the form to your server:

import { isEuCaptchaDone } from "@myrasec/eu-captcha";

function handleSubmit(e) {
  e.preventDefault();

  if (!isEuCaptchaDone()) {
    // challenge not yet complete — show a message or wait
    return;
  }

  // proceed with form submission
}

Callbacks

Use onComplete, onExpired, and onError to react to widget events without listening for window messages manually:

<EuCaptcha
  sitekey={captchaSitekey}
  onComplete={(token) => {
    // challenge complete — token is already written to the hidden input;
    // update state or enable your submit button here
    setVerified(true);
  }}
  onExpired={() => {
    // token has expired — prompt the user to re-verify
    setVerified(false);
  }}
  onError={() => {
    // network or server error during verification
    setError("CAPTCHA failed. Please try again.");
  }}
/>

Deferred execution

Set autostart={false} and provide a widgetId to suppress the automatic challenge, then trigger it programmatically:

<EuCaptcha
  sitekey={captchaSitekey}
  widgetId="login-captcha"
  autostart={false}
  onComplete={(token) => submitForm(token)}
/>

<button onClick={() => (window as any).euCaptcha.execute("login-captcha")}>
  Verify and submit
</button>

This is useful for forms where you want the challenge to start only when the user clicks the submit button, or when the widget is not immediately visible on page load.

Listening for completion

If you prefer to use the euCaptchaDone window message instead of the onComplete prop — for example, to enable a submit button from outside the component — listen for it in a useEffect:

import { useEffect } from "react";

useEffect(() => {
  function handleMsg(msg) {
    if (msg.data.type === "euCaptchaDone") {
      setSubmitEnabled(true);
    }
  }
  window.addEventListener("message", handleMsg, false);
  return () => window.removeEventListener("message", handleMsg, false);
}, []);

Retrieving the token

Once complete, the widget injects a hidden input into the surrounding <form>:

<input type="hidden" name="eu-captcha-response" value="<token>" />

If you are submitting via fetch or axios, read the token from the DOM or use the onComplete prop:

const token = document.querySelector('input[name="eu-captcha-response"]')?.value ?? "";

Pass it to your server endpoint and verify it with the verification API.

Next.js

App Router

Components that render <EuCaptcha> rely on browser APIs and must be Client Components. Add the 'use client' directive at the top of the file:

'use client';

import { EuCaptcha, isEuCaptchaDone } from "@myrasec/eu-captcha";

const captchaSitekey = "EUCAPTCHA_SITE_KEY";

export function ContactForm() {
  function handleSubmit(e: React.FormEvent<HTMLFormElement>): void {
    e.preventDefault();
    if (!isEuCaptchaDone()) return;
    // proceed with form submission
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* your fields */}
      <EuCaptcha sitekey={captchaSitekey} />
      <button type="submit">Submit</button>
    </form>
  );
}

Pages Router

Import the component with SSR disabled using next/dynamic:

import dynamic from "next/dynamic";
import { isEuCaptchaDone } from "@myrasec/eu-captcha";

const EuCaptcha = dynamic(
  () => import("@myrasec/eu-captcha").then((m) => m.EuCaptcha),
  { ssr: false }
);

const captchaSitekey = "EUCAPTCHA_SITE_KEY";

export function ContactForm() {
  function handleSubmit(e: React.FormEvent<HTMLFormElement>): void {
    e.preventDefault();
    if (!isEuCaptchaDone()) return;
    // proceed with form submission
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* your fields */}
      <EuCaptcha sitekey={captchaSitekey} />
      <button type="submit">Submit</button>
    </form>
  );
}

Gatsby

Gatsby pre-renders pages at build time, so components that access window or document will fail during gatsby build unless excluded from SSR. Use @loadable/component — the officially recommended Gatsby approach for browser-only components:

npm i @loadable/component

import loadable from "@loadable/component";
import { isEuCaptchaDone } from "@myrasec/eu-captcha";

const EuCaptcha = loadable(
  () => import("@myrasec/eu-captcha").then((m) => ({ default: m.EuCaptcha }))
);

const captchaSitekey = "EUCAPTCHA_SITE_KEY";

export function ContactForm() {
  function handleSubmit(e: React.FormEvent<HTMLFormElement>): void {
    e.preventDefault();
    if (!isEuCaptchaDone()) return;
    // proceed with form submission
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* your fields */}
      <EuCaptcha sitekey={captchaSitekey} />
      <button type="submit">Submit</button>
    </form>
  );
}

isEuCaptchaDone() and all other non-DOM imports from @myrasec/eu-captcha can be used without any guard. The widget <div> produces no SSR output during the build — this is expected.