--- name: netlify-forms description: Guide for using Netlify Forms for HTML form handling. Use when adding contact forms, feedback forms, file upload forms, or any form that should be collected by Netlify. Covers the data-netlify attribute, spam filtering, AJAX submissions, file uploads, notifications, and the submissions API. --- # Netlify Forms Netlify Forms collects HTML form submissions without server-side code. Form detection must be enabled in the Netlify UI (Forms section). > **Enabling detection only affects future deploys.** Netlify scans for forms at deploy time, so turning on (or re-enabling) form detection does **not** rescan your current live deploy. After enabling detection you must trigger a new deploy/build before an already-published form is registered and starts collecting submissions. ## Basic Setup Add `data-netlify="true"` and a unique `name` to the form: ```html
``` Netlify's build system detects the form and injects a hidden `form-name` input automatically. For a custom success page, add `action="/thank-you"` to the form tag. Use paths without `.html` extension — Netlify serves `thank-you.html` at `/thank-you` by default, and the `.html` path returns 404. ## JavaScript-Rendered Forms (React, Vue, SSR Frameworks) For forms rendered by JavaScript frameworks (React, Vue, Astro, TanStack Start, Next.js, SvelteKit, Remix, Nuxt), Netlify's build parser cannot detect the form in static HTML. You MUST create a static HTML skeleton file for build-time form detection: > **Form detection parses prerendered HTML only.** A `data-netlify` form is registered only if it appears in HTML produced at build time. On an Astro route that is server-rendered on demand (`export const prerender = false`, or an `output: "server"` route), the form is generated per request and is never scanned at build — so it is never registered. Put the form on a prerendered page, or add the static skeleton file below. Create a static HTML file in `public/` (e.g. `public/__forms.html`) containing a hidden copy of each form: ```html ``` **Rules:** - The form `name` must exactly match the `form-name` value used in your component's fetch call - Include every field your component submits — Netlify validates field names against the registered form - Without this file, Netlify cannot detect the form and submissions will silently fail Your component must also include a hidden `form-name` input: ```jsx
{/* ... fields ... */}
``` ## AJAX Submissions > **Netlify Forms does not accept JSON.** The submission body must be `application/x-www-form-urlencoded` (encode the fields with `URLSearchParams`) or `multipart/form-data` (a raw `FormData` object, for file uploads). A `fetch` that sends `JSON.stringify(...)` with `Content-Type: application/json` is silently **not** recorded as a submission — always send URL-encoded key/value pairs (or `FormData`), never JSON. ### Vanilla JavaScript ```javascript const form = document.querySelector("form"); form.addEventListener("submit", async (e) => { e.preventDefault(); const formData = new FormData(form); await fetch("/", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(formData).toString(), }); }); ``` > **SSR frameworks (TanStack Start, Next.js, SvelteKit, Remix, Nuxt):** The `fetch` URL must target the static skeleton > file path (e.g. `"/__forms.html"`), **not** `"/"`. In SSR apps, `fetch("/")` is intercepted by the SSR catch-all > function and never reaches Netlify's form processing middleware. See the React example and troubleshooting section below. ### React Example ```tsx function ContactForm() { const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); // For SSR apps, use the skeleton file path instead of "/" (e.g. "/__forms.html") const response = await fetch("/__forms.html", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(formData as any).toString(), }); if (response.ok) { // Show success feedback } }; return (