@hostily/captcha-react
v0.2.0
Published
React component for hostily Captcha (captcha.hostily.de): thin wrapper around the <hostily-captcha> web component. React 18 and 19, SSR-safe (Next.js).
Downloads
704
Maintainers
Readme
@hostily/captcha-react
Deutsch
React-Komponente für hostily Captcha: eine dünne Hülle um das Web Component <hostily-captcha>.
React 18 und 19, Next.js (App Router und Pages Router; die Komponente trägt "use client"), TypeScript-Typen inklusive.
Die Komponente liefert nur das Token. Das Secret gehört nie in den Browser – das Token prüft Ihr Server (z. B. mit @hostily/captcha).
npm install @hostily/captcha-react"use client";
import { useRef, useState } from "react";
import { HostilyCaptcha, type HostilyCaptchaHandle } from "@hostily/captcha-react";
export function Kontakt() {
const captcha = useRef<HostilyCaptchaHandle>(null);
const [token, setToken] = useState("");
return (
<form action="/api/kontakt" method="post">
<textarea name="nachricht" />
<HostilyCaptcha ref={captcha} siteKey="IHR_SITE_KEY" onVerify={setToken} onExpire={() => setToken("")} />
<button>Senden</button>
</form>
);
}Im Formular steht das Token im Feld hostily-captcha-token (nimmt <form> oder FormData automatisch mit); onVerify bekommt es zusätzlich.
Nach dem Absenden per Ajax captcha.current?.reset() aufrufen – ein Token gilt nur einmal.
| Prop | Bedeutung | Vorgabe |
|---|---|---|
| siteKey | Site-Key des Projekts (Pflicht) | – |
| api | Basisadresse des Dienstes | https://captcha.hostily.de/api/ |
| modus | "sichtbar" (Haken) / "unsichtbar" / "halten" (Taste gedrückt halten) / "schieben" (Schieberegler). „Halten“ und „Schieben“ bieten die Alternative „Lieber per Klick bestätigen“. Nicht gesetzt: der Modus des Projekts im Kundenportal | nicht gesetzt (Portal) |
| haltezeit | Millisekunden (800 bis 3000), nur für modus="halten" | 1500 |
| id, title, aria-*, data-* | werden unverändert ans Element gereicht (z. B. aria-describedby auf die Fehlermeldung) | – |
| sprache | "de" / "en" | aus <html lang> |
| theme | "hell" / "dunkel" | System |
| feld | Name des Token-Feldes | hostily-captcha-token |
| recaptchaKompatibel | zusätzlich g-recaptcha-response | aus |
| widgetUrl | Adresse des Widget-Skripts (selbst gehostet) | <api>/../widget/hostily-captcha.js |
| className | CSS-Klasse am Element | – |
| onVerify(token) | Token liegt vor | – |
| onError(meldung, code) | Fehler; code: netz, gesperrt, abgelehnt, challenge, rechnen, verfahren, skript | – |
| onExpire() | Token abgelaufen oder vom Widget zurückgesetzt (nicht nach eigenem reset()) | – |
Per ref: reset(), loesen() (Promise mit dem Token; im unsichtbaren Modus vor einem Absenden per Skript), token.
Das Widget-Skript wird einmal je Seite geladen, erst im Browser (SSR-sicher, keine Hydration-Warnungen).
CSP: script-src und connect-src für captcha.hostily.de, worker-src blob:, script-src 'wasm-unsafe-eval'.
Geprüft (Produktionsbuild, Browsertest gegen den echten Dienst): Next.js 14 mit React 18.3, Next.js 15 mit React 19.
Beispielprojekt: beispiel/, Test: test/lauf.sh.
English
React component for hostily Captcha: a thin wrapper around the <hostily-captcha> web component.
React 18 and 19, Next.js (the component carries "use client"), TypeScript types included. It only delivers the token; the secret
never belongs in the browser – your server verifies the token (e.g. with @hostily/captcha).
Usage as above. The token is in the form field hostily-captcha-token and is also passed to onVerify. After an Ajax submit call
reset() – a token is valid once. Props: siteKey (required), api, modus (sichtbar/unsichtbar/halten/schieben = checkbox/invisible/press-and-hold/slider; hold and slide offer a "confirm by click instead" button; unset = the mode of the project in the customer portal), haltezeit (ms, 800 to 3000, only for halten), sprache
(de/en), theme (hell/dunkel = light/dark), feld, recaptchaKompatibel, widgetUrl, className (plus id, title, aria-*, data-* passed through to the element), callbacks onVerify(token),
onError(message, code), onExpire() (not fired by your own reset()). Ref methods: reset(), loesen(), token.
The widget script is loaded once per page, in the browser only (SSR-safe). CSP: allow the service origin in script-src and
connect-src, plus worker-src blob: and script-src 'wasm-unsafe-eval'.
Tested (production build, browser test against the live service): Next.js 14 with React 18.3, Next.js 15 with React 19.
MIT
