FORMHUSH / React

Filter React contact form spam

Submit a React form to FormHush with JSON, a required website honeypot and clear pending, success and error states. Keep your existing styles.

A React form can send JSON directly to FormHush. The component below includes the required honeypot value and keeps the user’s message if receipt cannot be confirmed.

Add the contact component

Use this TypeScript component in your browser application. FormData reads the input values; the request body is explicitly serialized as JSON. Do not send the FormData object itself as the body.

Before connecting

Create a free account, confirm your email with the magic link, then open your dashboard. Your first form is created automatically. Add forms, allowed website origins and notification destinations in settings. Free includes 100 submissions per month; paid Solo and Studio plans are available through Polar. Resend delivers account emails and email notifications. Set an optional thank-you URL on one of your allowed website origins in Form settings.

The examples use https://api.formhush.com/f/example-contact. Replace the illustrative example-contact ID with your provisioned ID; it is not a live demo form. Keep account keys out of public markup. Browser requests must come from an exact allowed origin, including the scheme and any port.

import { useState, type FormEvent } from "react";

export default function ContactForm() {
  const [status, setStatus] = useState("");
  const [pending, setPending] = useState(false);

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    if (pending) return;
    const form = event.currentTarget;
    const data = new FormData(form);
    setPending(true);
    setStatus("Sending...");
    try {
      const response = await fetch("https://api.formhush.com/f/example-contact", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          name: data.get("name"),
          email: data.get("email"),
          message: data.get("message"),
          website: data.get("website")
        })
      });
      if (!response.ok) {
        setStatus(response.status === 429
          ? "Submission limit reached. Please try again later."
          : "Message not accepted. Check your details and try again.");
        return;
      }
      form.reset();
      setStatus("Message received.");
    } catch {
      setStatus("Could not confirm receipt. Your text is still here; check before retrying.");
    } finally {
      setPending(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <label>Name <input name="name" maxLength={120} autoComplete="name" /></label>
      <label>Email <input name="email" type="email" maxLength={254} autoComplete="email" /></label>
      <label>Message <textarea name="message" maxLength={8000} required /></label>
      <input name="website" type="text" hidden tabIndex={-1} autoComplete="off" />
      <button type="submit" disabled={pending}>Send message</button>
      <p role="status">{status}</p>
    </form>
  );
}

Success and retry behaviour

The example disables the button while a request is pending and clears fields only after an accepted response. A network error can occur after the server has stored a message, so avoid automatic retries that could create duplicates. An HTTP 429 can mean a rate limit or a monthly quota; inspect the error body and Retry-After header when building more detailed feedback.

For a form without a JavaScript submit handler, use the HTML guide. The same field contract applies.

Fields and thank-you behaviour

message is required, up to 8,000 characters. name is optional, up to 120 characters; email is optional, up to 254 characters and must be valid when supplied. The website string is mandatory and must stay empty for a legitimate visitor. A filled honeypot is stored as spam, not silently discarded.

Only JSON and URL-encoded POST bodies are accepted, with a 16,384-byte limit. Up to 20 additional text fields are stored and delivered, with at most 2,000 characters each and 8,000 in total. Field names must start with a letter or underscore and contain only letters, digits, underscores, dots, spaces or hyphens (64 characters maximum). Arrays, objects, repeated names and file uploads are rejected. FormHush does not use _gotcha, and a submitted _redirect does not control navigation.

Native URL-encoded forms receive HTTP 303 to the FormHush confirmation page by default. In Form settings, choose an HTTPS thank-you page on an allowed website origin to use your own. JSON requests, or URL-encoded requests with Accept: application/json, receive HTTP 201 JSON; JavaScript forms handle their own success state after checking the response. Native form errors show a readable error page; entered text is not echoed. For iframe forms, set a custom thank-you page that allows framing, or use a JSON form with an inline success state.

Classification, delivery and retention

Only a filled honeypot is deterministically classified as spam. Links and quoted spam phrases are evaluated in context by AI. When configured, Jev classifies the remaining message text after email addresses and phone numbers are masked. That masking is not complete anonymisation. Ambiguous decisions stay in Needs review. Forward them or mark them as spam in the dashboard. A daily email reminder covers unresolved messages from previous days and contains no submission content.

Real leads and urgent messages are queued for configured destinations. When AI is unavailable, remaining accepted messages become Unsorted and are also queued; the honeypot check still applies. Delivery adapters support email, Slack, Telegram and webhooks, configured in your dashboard. Email delivery uses Resend. Retries do not guarantee that a third party receives a message.

Submissions and related notification jobs are deleted after 30 days by scheduled cleanup. Copies sent to your channels follow those services’ retention policies. Processing can involve the United States; see the privacy policy for providers and details.

Spam and sales pitches do not count toward your monthly quota. Other accepted messages reserve a place while classification is pending. At the cap, a new message needing a place is rejected; you receive an alert at 80% and 100%. Rate limits still apply to all submissions.

Test the complete flow

1. Test from an allowed origin using a provisioned form. Submit a clear enquiry and check its stored result in the dashboard.
2. Check delivery separately, using a configured test destination. An accepted response alone does not prove notification delivery.
3. Send a nonempty message with website filled to verify that it is stored as spam without notification. An empty message is a validation error, not a spam verdict.
4. Confirm a missing honeypot or empty message returns HTTP 400, an unsupported body format returns HTTP 415, and a disallowed browser origin returns HTTP 403.
5. Verify the thank-you page or inline success message and preserve entered text on errors. Rate and monthly limits return HTTP 429; respect Retry-After before retrying. Check for a stored record after a network failure to avoid duplicate submissions.