Contact form for Gatsby websites

Drop the React component above into src/components/ContactForm.jsx, set GATSBY_SPLITFORMS_KEY in your .env, and import the component on any page. No plugin, no gatsby-config edits required.

Yes — both. The component is a standard React function component, no Gatsby-specific APIs. For v5 partial hydration, add 'use client' at the top of the file so the onSubmit handler binds on the client.

Use a status state with four values: idle, loading, ok, err. Render error messages from data.message inside an {status === 'err' && …} block. The fetch returns { success, message? }.

You can, but you don't need to. The whole point of splitforms is replacing the function. If you do want a server-side proxy (to hide the key entirely), POST from a Gatsby Function and forward to splitforms — same backend.

Two options. (1) Stay on-page with a React-rendered success message (default in our snippet), or call Gatsby's navigate() after success. (2) For a native form post, configure the absolute /thanks URL in Dashboard → Form settings → Redirect. Submitted redirect fields are ignored.

Yes — every host. The form posts to splitforms.com from the static page, regardless of where the static files are served from. Splitforms's allowed-domains list just needs to include your live URL.

Gatsby's webpack config only exposes process.env.* variables prefixed with GATSBY_. If you write process.env.SPLITFORMS_KEY, you'll get undefined in the browser bundle. Rename to GATSBY_SPLITFORMS_KEY — and accept that it's bundled into the static JS (lock the key to your domain in the splitforms dashboard).

Gatsby's <Link> component prevents default navigation. Do not wrap the form in a Link. For fetch-based forms, call Gatsby's navigate('/thanks') after a successful response. For native form posts, configure the absolute thank-you URL in the splitforms dashboard.

If you use useState('idle') in your form and render any state-dependent UI on first paint, Gatsby's static HTML and React's client render can diverge — you'll see a hydration warning. Render the form unconditionally; only render status messages inside the handler-triggered branches.

Gatsby 5 introduced partial hydration via React Server Components. If your form is in a Server Component, the onSubmit handler won't bind. Add 'use client' at the top of the file (or use a separate ContactForm.client.jsx).

Older Gatsby setups used @reach/router, which has a known issue where it sometimes intercepts form submissions. If you see your form not POSTing, ensure you've migrated to Gatsby v4+ (uses its own router) or wrap the form in a normal <div> not <Router>.

If your site uses gatsby-plugin-offline (or the older gatsby-plugin-manifest with service worker registration), the contact page HTML is cached aggressively. After you rotate your GATSBY_SPLITFORMS_KEY and redeploy, returning visitors keep submitting against the old key from the cached bundle until the service worker fetches a fresh shell — sometimes days. Fix: bump the SW cache version in gatsby-config.js on key rotation, or skip the offline plugin on the contact route via runtimeCaching rules. Alternatively, switch to gatsby-plugin-pwa which handles versioned cache invalidation per-page.

Gatsby builds a static React app, so 'native' means choosing between (a) Netlify Forms for Gatsby sites hosted on Netlify, with gatsby-plugin-netlify required, (b) Gatsby Functions (deprecated in Gatsby 5 — they were removed when Gatsby Cloud shut down), or (c) a third-party form backend. Gatsby v4 had Functions running as Lambda-equivalent serverless routes; v5 removed them entirely. Result: every Gatsby contact form today uses an external service. Splitforms is the portable drop-in option — the same POST shape as Netlify Forms or Formspree, with built-in spam filtering.

Gatsby builds static HTML + JS that deploys to any host: Netlify, Vercel, Cloudflare Pages, AWS Amplify, S3 + CloudFront, Gatsby Cloud (sunset 2024 — migrate). The form posts cross-origin to splitforms regardless of host. Env vars exposed to the browser bundle must be prefixed GATSBY_ — anything else is undefined client-side. The key gets bundled into the JS at build time; lock it to your domain in the splitforms dashboard. For headless Gatsby + WordPress / Contentful setups, the form lives in the React tree, not the CMS — no special CMS wiring required.