React (@frontmail/react)

npm install @frontmail/react

Działa z Reactem 18 i 19, także z Next.js (używaj w komponentach klienckich).

Provider

Owiń aplikację (albo tylko część z formularzami) w FrontmailProvider. Obiekt z opcjami powinien być stabilny – zdefiniuj go na poziomie modułu albo przez useMemo:

import { FrontmailProvider } from '@frontmail/react';

const frontmailOptions = { publicKey: 'pk_4f2a…', blockHeadless: true };

export function App() {
  return (
    <FrontmailProvider options={frontmailOptions}>
      <Routes />
    </FrontmailProvider>
  );
}

options przyjmuje to samo co init(). Możesz też przekazać istniejącego klienta: <FrontmailProvider client={client}>.

FrontmailForm

Najszybsza droga do działającego formularza – wysyła przez sendForm, renderuje Turnstile, gdy przekażesz site key, i udostępnia stan wysyłki:

import { FrontmailForm } from '@frontmail/react';

export function ContactForm() {
  return (
    <FrontmailForm
      serviceId="svc_01J9…"
      templateId="tpl_contact"
      turnstileSiteKey="YOUR_TURNSTILE_SITE_KEY"
      onSuccess={(result) => console.log(result.status)}
      onError={(error) => console.error(error.code)}
    >
      {({ status, error }) => (
        <>
          <input name="name" required />
          <input name="email" type="email" required />
          <textarea name="message" required />
          <button disabled={status === 'sending'}>Wyślij</button>
          {status === 'sent' && <p>Dziękujemy!</p>}
          {status === 'held' && <p>Otrzymaliśmy – wkrótce ją dostarczymy.</p>}
          {error && <p role="alert">{error.message}</p>}
        </>
      )}
    </FrontmailForm>
  );
}

Propsy: serviceId, templateId, turnstileSiteKey, turnstileOptions, locale, sendOptions, resetOnSuccess (domyślnie true), onSuccess, onError oraz dowolny atrybut <form>. Dziećmi mogą być węzły albo funkcja stanu { status, error, result }.

locale (np. "de") wysyła e-mail w tym języku szablonu (jako pole formularza fm_locale; pole fm_locale wewnątrz formularza ma pierwszeństwo). result.locale to użyty język.

turnstileSiteKey to site key twojego własnego widgetu Turnstile (w panelu Bezpieczeństwo → Ochrona przed botami (Turnstile)) – zobacz Cloudflare Turnstile. Jeśli szablon nie wymaga CAPTCHA, pomiń go.

useSendEmail

Dla własnego UI i formularzy kontrolowanych:

import { useState } from 'react';
import { useSendEmail } from '@frontmail/react';

function Newsletter() {
  const { send, status, error, reset } = useSendEmail('svc_01J9…', 'tpl_newsletter');
  const [email, setEmail] = useState('');

  return (
    <form onSubmit={async (e) => { e.preventDefault(); await send({ email }); }}>
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <button disabled={status === 'sending'}>Zapisz się</button>
      {status === 'error' && <p role="alert">{error?.message}</p>}
    </form>
  );
}

status przechodzi idle → sending → sent | held | error. send() i sendForm() zwracają wynik albo – przy błędzie – undefined (błąd jest w error), więc nie potrzebujesz try/catch. Obie przyjmują opcje jako drugi argument, np. send({ email }, { locale: 'de' }).

useFrontmail

Zwraca klienta z providera do wszystkiego innego, np. getStatus:

import { useFrontmail } from '@frontmail/react';

const client = useFrontmail();
const status = await client.getStatus(messageId, { token });

Typowane parametry

Z wygenerowanymi typami useSendEmail('svc_…', 'tpl_contact').send({...}) sprawdza typy parametrów danego szablonu.

Przykładowy projekt: examples/react.