React (@frontmail/react)

npm install @frontmail/react

Funguje s Reactem 18 i 19, včetně Next.js (používejte v klientských komponentách).

Provider

Obalte aplikaci (nebo jen část s formuláři) do FrontmailProvider. Objekt s volbami udržujte stabilní – definujte ho na úrovni modulu nebo pomocí useMemo:

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

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

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

options přijímá totéž co init(). Případně můžete předat existujícího klienta: <FrontmailProvider client={client}>.

FrontmailForm

Nejrychlejší cesta k funkčnímu formuláři – odesílá přes sendForm, vykreslí Turnstile, když předáte site key, a zpřístupní stav odesílání:

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'}>Odeslat</button>
          {status === 'sent' && <p>Děkujeme!</p>}
          {status === 'held' && <p>Přijato – brzy ji doručíme.</p>}
          {error && <p role="alert">{error.message}</p>}
        </>
      )}
    </FrontmailForm>
  );
}

Props: serviceId, templateId, turnstileSiteKey, turnstileOptions, sendOptions, resetOnSuccess (výchozí true), onSuccess, onError a jakýkoli atribut <form>. Potomky mohou být uzly, nebo funkce stavu { status, error, result }.

turnstileSiteKey je site key vašeho vlastního widgetu Turnstile (v dashboardu Zabezpečení → Ochrana proti botům (Turnstile)) – viz Cloudflare Turnstile. Pokud šablona CAPTCHA nevyžaduje, vynechte ho.

useSendEmail

Pro vlastní UI a řízené formuláře:

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'}>Přihlásit k odběru</button>
      {status === 'error' && <p role="alert">{error?.message}</p>}
    </form>
  );
}

status přechází idle → sending → sent | held | error. send() a sendForm() se resolvnou s výsledkem, nebo při chybě s undefined (chyba je v error), takže try/catch nepotřebujete.

useFrontmail

Vrací klienta z provideru pro všechno ostatní, např. getStatus:

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

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

Typované parametry

S vygenerovanými typy typově kontroluje useSendEmail('svc_…', 'tpl_contact').send({...}) parametry dané šablony.

Ukázkový projekt: examples/react.