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
fetchas 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
| Attribute | On | What it does |
|---|---|---|
data-formham="ID" | form | Binds the form, if its action does not already point at FormHam. |
data-formham-sending | form | Button text while sending. Default “Sending…”. |
data-formham-success | form | Message shown after success. Default “Thanks — your message has been sent.” |
data-formham-status | element inside the form | Where messages are written. If there is none, one is created with role="status". |
data-debug | script tag | Logs 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.