🤖 Friendly Captcha for React

Modern, type-safe React bindings for Friendly Captcha v2, built on the official @friendlycaptcha/sdk.

[!IMPORTANT] Unofficial & unaffiliated. This is a community package maintained by nexum AG. It is not developed, endorsed, or supported by Friendly Captcha GmbH, and nexum AG is not affiliated with Friendly Captcha in any way. "Friendly Captcha" is a trademark of its respective owner and is used here only to describe what this package integrates with. For the official product and SDK, see friendlycaptcha.com.

👉 Getting Started

🧩 Usage

🔒 Server-side verification

🛠️ Configuration

🧪 Local development

🐾 Useful links

👉 Getting Started

npm install @nexum-ag/friendly-captcha

[!NOTE] react 19+ is the only peer dependency. The Friendly Captcha SDK is bundled as a dependency, so you don't install it separately.

Render the widget inside your <form>. It injects a hidden frc-captcha-response input, so the token is submitted automatically with the form:

import { FriendlyCaptcha } from "@nexum-ag/friendly-captcha";

function ContactForm() {
  return (
    <form method="POST" action="/api/contact">
      <input name="email" type="email" required />
      <FriendlyCaptcha sitekey="FCMxxxxxxxxxxxxxxx" />
      <button type="submit">Send</button>
    </form>
  );
}

🧩 Usage

This package ships two ways to use the widget — a declarative component and a headless hook — plus a server-side verification helper.

Component

Capture the token via onComplete when you control submission yourself:

const [token, setToken] = useState<string | null>(null);

<FriendlyCaptcha
  sitekey="FCMxxxxxxxxxxxxxxx"
  onComplete={setToken}
  onExpire={() => setToken(null)}
/>;

The component forwards a ref with imperative helpers:

const ref = useRef<FriendlyCaptchaHandle>(null);
// ref.current?.reset();
// ref.current?.getResponse();
<FriendlyCaptcha ref={ref} sitekey="…" />;

Hook

For full control, useFriendlyCaptcha() returns a ref to attach plus reactive state:

import { useFriendlyCaptcha } from "@nexum-ag/friendly-captcha";

function Captcha() {
  const { ref, state, response, solved, error, reset } = useFriendlyCaptcha({
    sitekey: "FCMxxxxxxxxxxxxxxx",
    onComplete: (token) => console.log("solved", token),
  });

  return (
    <div>
      <div ref={ref} className="frc-captcha" />
      {error && <button onClick={reset}>Retry</button>}
    </div>
  );
}

[!NOTE] response is the normalized token — internal sentinel values (e.g. .SOLVING) are surfaced as null. Use solved for a simple "is there a token" check.

Props & options

All of the SDK's createWidget options are accepted by both the component and the hook:

| Option | Type | Default | Notes | | --------------- | ----------------------------- | ------------------------ | ---------------------------------- | | sitekey | string | — | Your sitekey (FC…). | | startMode | "auto" \| "focus" \| "none" | "focus" | When the challenge starts solving. | | theme | "light" \| "dark" \| "auto" | "light" | Widget appearance. | | language | string | auto-detected | e.g. "en", "de". | | formFieldName | string \| null | "frc-captcha-response" | Hidden input name. | | apiEndpoint | "global" \| "eu" \| string | "global" | Data residency / custom endpoint. |

Callbacks: onComplete(token), onError(error), onExpire(), onReset(), onStateChange(state).

🔒 Server-side verification

[!IMPORTANT] Always verify the token on your server — a client-side token alone is not proof. Your API key is a secret and must never reach the browser.

The helper lives in a separate entry point and depends only on fetch, so it runs on Node 22+, Deno, Bun, edge runtimes, and Cloudflare Workers:

import { verifyCaptchaResponse } from "@nexum-ag/friendly-captcha/server";

const result = await verifyCaptchaResponse({
  response: formData.get("frc-captcha-response") as string,
  apiKey: process.env.FRC_API_KEY!, // secret — server only
  // endpoint: "eu",                // optional, defaults to "global"
});

if (!result.success) {
  // result.errorCode, result.detail, result.status
  return new Response("Captcha failed", { status: 400 });
}
// result.eventId, result.challengeTimestamp, result.origin

[!NOTE] A 200 status does not mean the solution was valid — always branch on result.success. The helper never throws: transport failures come back as { success: false, errorCode: "network_error" }.

See examples/astro for an end-to-end demo using an Astro Action (a server function) to verify the token.

🛠️ Configuration

Sharing & configuring the SDK

By default a single SDK instance is created lazily and shared. To customize it — EU data residency, or relaxing eval-patching for a strict CSP — wrap your app in the provider:

import { FriendlyCaptchaProvider } from "@nexum-ag/friendly-captcha";

<FriendlyCaptchaProvider options={{ apiEndpoint: "eu", disableEvalPatching: true }}>
  <App />
</FriendlyCaptchaProvider>;

You can also pass an sdk instance directly to the provider, hook, or component.

[!NOTE]

• SSR / islands: the component renders a placeholder element on the server and activates the widget on the client, so it's safe with Astro islands (client:load), Next, etc. — the SDK is never constructed during render.
• Security: the API key is server-only. Only import /server on the server.
• CSP: the SDK patches window.eval; set disableEvalPatching: true if your CSP forbids it (this can affect some dev hot-reload setups).
• Data residency: set apiEndpoint on the widget and endpoint on the verify helper to "eu" for EU-only processing.
• TypeScript: both entry points resolve under bundler, node16 and nodenext. Declarations are self-contained, so you don't need @friendlycaptcha/sdk's own types to be resolvable. WidgetHandle and FriendlyCaptchaSDK are exposed as structural interfaces — an SDK instance you construct yourself is assignable to them, but not the other way round (the SDK's classes have private members). To pass a widget or SDK this package returns to code typed against @friendlycaptcha/sdk, cast it (as unknown as import("@friendlycaptcha/sdk").WidgetHandle) or keep a reference to your own instance.

🧪 Local development

Requires Node 22.22+ or 24.15+ (an active or maintenance LTS line — Node 20 is end-of-life).

npm install
npm run build         # build dist/ (ESM + CJS + types)
npm test              # vitest
npm run test:coverage # vitest + coverage report
npm run typecheck     # tsc --noEmit
npm run lint          # oxlint
npm run format        # oxfmt
npm run check:pkg     # build, then publint + are-the-types-wrong

Run the example (after building the library so its dist/ exists):

npm run build
cd examples/astro
npm install         # links the library via file:../..
cp .env.example .env  # add your sitekey + API key
npm run dev

Tech stack

• Vite — library build (ESM + CJS + types) and the Vitest test runner.
• Vitest — unit tests, jsdom + Testing Library.
• oxc — oxlint for linting and oxfmt for formatting.
• Published to npm on each GitHub release (the version is taken from the release tag).

🐾 Useful links

• Friendly Captcha v2 docs
• Widget SDK reference
• siteverify API
• @friendlycaptcha/sdk on npm

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE.

Copyright © nexum AG and its associated companies.