React (@frontmail/react)

npm install @frontmail/react

Funguje s Reactom 18 aj 19 vrátane Next.js (používajte v klientskych komponentoch).

Provider

Obaľte aplikáciu (alebo len časť s formulármi) do FrontmailProvider. Objekt s voľbami udržujte stabilný – definujte ho na úrovni modulu alebo pomocou useMemo:

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

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

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

options prijíma to isté čo init(). Prípadne môžete odovzdať existujúceho klienta: <FrontmailProvider client={client}>.

FrontmailForm

Najrýchlejšia cesta k funkčnému formuláru – odosiela cez sendForm, vykreslí Turnstile, keď odovzdáte site key, a sprístupní stav odosielania:

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'}>Odoslať</button>
          {status === 'sent' && <p>Ďakujeme!</p>}
          {status === 'held' && <p>Prijaté – čoskoro ju doručíme.</p>}
          {error && <p role="alert">{error.message}</p>}
        </>
      )}
    </FrontmailForm>
  );
}

Props: serviceId, templateId, turnstileSiteKey, turnstileOptions, locale, sendOptions, resetOnSuccess (predvolene true), onSuccess, onError a akýkoľvek atribút <form>. Potomkami môžu byť uzly alebo funkcia stavu { status, error, result }.

locale (napr. "de") pošle e-mail v zadanom jazyku šablóny (ako pole formulára fm_locale; pole fm_locale priamo vo formulári má prednosť). result.locale je použitý jazyk.

turnstileSiteKey je site key vášho vlastného widgetu Turnstile (v dashboarde Zabezpečenie → Ochrana pred botmi (Turnstile)) – pozrite Cloudflare Turnstile. Ak šablóna CAPTCHA nevyžaduje, vynechajte ho.

useSendEmail

Pre vlastné UI a riadené formuláre:

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'}>Prihlásiť sa na odber</button>
      {status === 'error' && <p role="alert">{error?.message}</p>}
    </form>
  );
}

status prechádza idle → sending → sent | held | error. send() a sendForm() sa resolvnú s výsledkom alebo pri chybe s undefined (chyba je v error), takže try/catch nepotrebujete. Obe berú voľby ako druhý argument, napr. send({ email }, { locale: 'de' }).

useFrontmail

Vracia klienta z providera pre všetko ostatné, napr. getStatus:

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

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

Typované parametre

S vygenerovanými typmi typovo kontroluje useSendEmail('svc_…', 'tpl_contact').send({...}) parametre danej šablóny.

Ukážkový projekt: examples/react.