A Drop-In JavaScript Form Helper for Any Static Site

One script tag gives your HTML form a complete backend: AJAX submission, inline validation, CAPTCHA and lifecycle events. No build step, no framework lock-in.

StaticForm Team
On this page

Adding a working contact form to a static site used to mean standing up a backend, wiring a CAPTCHA provider, and writing the same pile of submit glue code on every project: a fetch handler, loading state, validation that maps server errors back to the right input, a success message, a network-error fallback. Nobody enjoys writing it twice.

You don’t actually need any of it to use StaticForm. A plain HTML <form action="…" method="POST"> works fine. The backend accepts it, validates it, and, once you pick a success redirect in the form’s dashboard settings, sends the visitor to a hosted thank-you page. But for most sites you want to keep the user on the page, show errors next to the offending field, and add CAPTCHA without wiring a provider by hand.

That’s what our drop-in helper is for. It’s a tiny (~2.6 KB gzipped), framework-agnostic script you add to any page. One script tag, one function call, and you get the polished submit experience without writing submit code yourself.

Here’s how it works.

What the helper does for you

  • A submit handler that POSTs FormData to your StaticForm endpoint
  • Field-level error rendering from the API’s ProblemDetails response
  • CAPTCHA integration for reCAPTCHA v3, reCAPTCHA v2, Cloudflare Turnstile, and hCaptcha. The provider’s loader script is injected for you.
  • Focus, blur, and input styling so fields visually reset as the user types
  • Custom events (sf:submitting, sf:success, sf:error, sf:settled) for loading spinners and thank-you messages
  • A network-error fallback so a dropped connection doesn’t look like a silent failure

No build step. No dependencies. Works with plain HTML, Astro, Eleventy, Hugo, Jekyll, or anything else that outputs static pages.

Step 1: Include the script

Drop it in before the closing </body> tag:

<script src="https://staticform.app/scripts/staticform.js" defer></script>

Point at the copy we host, or download it and serve it yourself.

Step 2: Write plain HTML

No special components. Just a regular form with name attributes, plus one error placeholder per field. Each name must match a field defined on the form in the StaticForm dashboard; inputs with any other name are dropped:

<form id="contact-form">
  <label>
    Email
    <input name="email" type="email" required>
  </label>
  <p data-sf-error="email"></p>

  <label>
    Message
    <textarea name="message" required></textarea>
  </label>
  <p data-sf-error="message"></p>

  <p data-sf-general-error></p>

  <button type="submit">Send</button>
</form>

Two conventions to remember:

  • data-sf-error="fieldname" marks the element that will receive the error text for a given field.
  • data-sf-general-error marks the element that will receive any error not tied to a specific field (network issues, rate limits, etc.). CAPTCHA failures arrive under the name captcha, so add a <p data-sf-error="captcha"></p> if you use CAPTCHA.

Both start empty and are only shown if there’s something to say.

Step 3: Attach the handler

Grab a form endpoint from your StaticForm dashboard and call attach:

<script>
  document.addEventListener('DOMContentLoaded', () => {
    StaticForm.attach(document.getElementById('contact-form'), {
      endpoint: 'https://api.staticform.app/api/v1/forms/YOUR_FORM_ID',
    });
  });
</script>

The DOMContentLoaded wrapper matters: an inline script runs before the deferred staticform.js has loaded, so calling StaticForm.attach directly would throw ReferenceError: StaticForm is not defined.

That’s it. Submit the form. The helper will POST it, render any validation errors next to the right fields, and reset the form on success.

Adding CAPTCHA

One extra config block. The helper injects the provider’s loader script automatically if it’s not already on the page:

<script>
  document.addEventListener('DOMContentLoaded', () => {
    StaticForm.attach(document.getElementById('contact-form'), {
      endpoint: 'https://api.staticform.app/api/v1/forms/YOUR_FORM_ID',
      captcha: {
        type: 'turnstile',          // or 'recaptcha-v3', 'recaptcha-v2', 'hcaptcha'
        siteKey: 'YOUR_SITE_KEY',   // required for recaptcha-v3
      },
    });
  });
</script>

Select the same provider and enter its secret key in the form’s CAPTCHA settings in the dashboard. The API only verifies tokens for forms that have CAPTCHA turned on there.

For widget-based providers (Turnstile, reCAPTCHA v2, hCaptcha) you render the widget in your markup as usual; the helper preserves that form’s local token and resets only its identified widget after each submission. Custom explicit renderers can pass the provider’s returned id as captcha.widgetId, or a function returning it; see the helper guide. For reCAPTCHA v3 the token is generated programmatically.

If you load the provider script yourself (for example with a custom CSP nonce), pass loadScript: false inside captcha to opt out of auto-injection.

Hooking into events

For a thank-you message, a loading spinner, or analytics, listen to the custom events the helper dispatches on the form:

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const form = document.getElementById('contact-form');

    form.addEventListener('sf:submitting', () => {
      form.querySelector('button').disabled = true;
    });

    form.addEventListener('sf:success', () => {
      document.getElementById('thanks').hidden = false;
    });

    form.addEventListener('sf:settled', () => {
      form.querySelector('button').disabled = false;
    });

    StaticForm.attach(form, {
      endpoint: 'https://api.staticform.app/api/v1/forms/YOUR_FORM_ID',
    });
  });
</script>

sf:submitting fires when the submit handler runs. sf:success fires on a 2xx response with the parsed body in event.detail. sf:error fires on any failure with the error array in event.detail. sf:settled fires at the end of every submit, success or failure, which makes it the right hook for re-enabling the button.

Prefer callbacks? Pass onSuccess and onError to attach instead; they receive the same payloads.

Customizing the look

The helper applies subtle focus, blur, and error border styles so fields look alive as the user interacts. Every color and border is overridable:

StaticForm.attach(form, {
  endpoint: '…',
  styles: {
    errorColor:          '#dc2626',
    focusColor:          'rgba(59,130,246,0.5)',
    focusShadow:         '0 0 0 3px rgba(59,130,246,0.15)',
    defaultBorderStyle:  '1px solid #e5e7eb',
    errorBorderStyle:    '1px solid #dc2626',
  },
});

Or leave styles out entirely and write your own CSS against the fields and error elements. The helper won’t fight you.

That’s the whole thing

One script tag, one call to StaticForm.attach, and you’ve skipped the entire stack of form glue code most sites end up writing from scratch. No framework lock-in, no build pipeline, no server to run. If you ever outgrow the helper, the endpoint still accepts a plain HTML POST, so nothing locks you in.

If you haven’t yet, create a form in the dashboard, copy the endpoint, and paste it in. You’ll have a working contact form before your coffee cools off.

For the full option reference, including every config key, event payload, and CAPTCHA nuance, see the JavaScript helper docs.

Using a framework?

The helper works everywhere, but if you want framework-specific examples (mounting on client-side navigation, handling hydration, or using native form primitives), we have dedicated walkthroughs:

Evaluating other form backends? See how StaticForm compares to the alternatives, including a hands-on breakdown of StaticForms.dev.