Docs

JavaScript embed

One script tag. It submits without a page reload, answers the spam check for you, and falls back to a normal form post if anything goes wrong.

Add it

<form action="https://app.formham.co.uk/submit/YOUR-FORM-ID" method="POST" data-formham="YOUR-FORM-ID">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>

<script src="https://app.formham.co.uk/embed/formham.js" defer></script>

The script picks up every form with a data-formham attribute, and every form whose action already points at a FormHam /submit/… endpoint — so an existing HTML form needs only the script tag. Forms added to the page later (in a modal, or by a framework) are picked up automatically. Keep the action and method: they are what makes the form work for anyone with JavaScript off.

What it does

  • Adds a hidden honeypot field.
  • Reads the form's settings and, depending on its spam protection, answers the built-in check in the background or loads Google reCAPTCHA v3 and fetches a token at submit.
  • Sends the form with fetch as JSON (or multipart, if the visitor chose a file), adding the page URL and title. No cookies are sent or set.
  • On success, follows the form's Redirect URL if it has one; otherwise resets the form and shows a thank-you message.
  • If any step fails — the check, reCAPTCHA, the network — it still sends the submission rather than lose it. Worst case, it lands in quarantine for you to review.

reCAPTCHA v2 (the checkbox) is not supported by the embed: a form set to v2 is submitted without a token and will be held for review. Use v3, or the built-in check.

Attributes

AttributeOnWhat it does
data-formham="ID"formBinds the form, if its action does not already point at FormHam.
data-formham-sendingformButton text while sending. Default “Sending…”.
data-formham-successformMessage shown after success. Default “Thanks — your message has been sent.”
data-formham-statuselement inside the formWhere messages are written. If there is none, one is created with role="status".
data-debugscript tagLogs what the script is doing to the browser console.

The script talks to whichever host it was loaded from, so always load it from https://app.formham.co.uk.

Events

Both events bubble from the form, so you can listen on the form or on document:

document.addEventListener('formham:success', function (e) {
  // e.detail is the JSON response: submission_id, receipt_id, redirect_url…
  console.log('Sent', e.detail.receipt_id);
});

document.addEventListener('formham:error', function (e) {
  // e.detail is an Error
  console.warn('Not sent', e.detail.message);
});

formham:success does not fire when the form has a Redirect URL, because the browser is already leaving the page.

Rescanning by hand

The script exposes window.formham.scan(), which binds any FormHam forms on the page that are not bound yet. You should rarely need it.