npx skills add ...
npx skills add netlify/context-and-tools --skill netlify-forms
npx skills add netlify/context-and-tools --skill netlify-forms
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 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.
Add data-netlify="true" and a unique name to the form:
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.
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-netlifyform 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 anoutput: "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:
Rules:
name must exactly match the form-name value used in your component's fetch callYour component must also include a hidden form-name input:
Netlify Forms does not accept JSON. The submission body must be
application/x-www-form-urlencoded(encode the fields withURLSearchParams) ormultipart/form-data(a rawFormDataobject, for file uploads). Afetchthat sendsJSON.stringify(...)withContent-Type: application/jsonis silently not recorded as a submission — always send URL-encoded key/value pairs (orFormData), never JSON.
SSR frameworks (TanStack Start, Next.js, SvelteKit, Remix, Nuxt): The
fetchURL 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.
SSR troubleshooting: If form submissions appear to succeed (200 response) but nothing shows in the Netlify Forms UI, the POST is likely being intercepted by the SSR function. Ensure
fetchtargets the skeleton file path (e.g."/__forms.html"), not"/". The skeleton file path routes through the CDN origin where Netlify's form handler runs.
Netlify uses Akismet automatically. Add a honeypot field for extra protection:
For reCAPTCHA, add data-netlify-recaptcha="true" to the form and include <div data-netlify-recaptcha="true"></div> where the widget should appear.
By default Netlify provisions and verifies the reCAPTCHA for you — do not add a site key/secret or load Google's reCAPTCHA script yourself. To use your own reCAPTCHA v2 keys, keep the same data-netlify-recaptcha="true" markup and set the credentials as Netlify environment variables: SITE_RECAPTCHA_KEY (the site key, scoped to Builds and Runtime) and SITE_RECAPTCHA_SECRET (the secret, scoped to Runtime). Netlify picks these up automatically — the secret stays server-side as an env var (never hardcoded in client code), and you still don't render the widget with Google's own script or build a custom Function to verify the token.
Spam submissions are silent. Akismet-flagged submissions are moved to a separate Spam list in the Forms UI — they do not appear in the verified submissions list and do not trigger email/Slack notifications. Submissions caught by a honeypot field or a failed reCAPTCHA challenge are discarded entirely and never appear in either list. So a "missing" legitimate submission is usually a false-positive spam classification, not a delivery bug: check the Spam list (or the Submissions API with
?state=spam) and mark it verified — do not build a custom Function to "recover" it or disable spam filtering as a first resort.
For AJAX file uploads, use FormData directly — do not set Content-Type (the browser sets it with the correct boundary):
Limits: 8 MB max request size, 30-second timeout, one file per input field.
Configure in the Netlify UI under Project configuration > Notifications:
<input type="hidden" name="subject" value="Contact form" /> for custom subject lines.Access submissions programmatically:
Key endpoints:
| Action | Method | Path |
|---|---|---|
| List forms | GET | /api/v1/sites/{site_id}/forms |
| Get submissions | GET | /api/v1/forms/{form_id}/submissions |
| Get spam | GET | /api/v1/forms/{form_id}/submissions?state=spam |
| Delete submission | DELETE | /api/v1/submissions/{id} |
The Netlify API paginates any response over 100 items (100 per page by default). Pass ?page= (1-based) and optionally ?per_page= (max 100), and follow the Link response header — it carries the rel="next" and rel="last" page URLs. To sync every submission, page through until there is no rel="next" link (or a page returns fewer than per_page items). A single request does not return all submissions once a form has more than 100 — code that reads only the first response silently drops the rest.
To manage forms or read submissions programmatically, use the documented netlify CLI or the Submissions API above with an explicit personal access token supplied via an environment variable. Do not go around the documented surface:
https://api.netlify.com/... with an invented endpoint shape, and do not run netlify api <method> as a recovery hatch when a documented path fails.~/Library/Preferences/netlify/config.json (or anywhere on disk) — it comes from the configured env var.If a documented path fails, report the exact error and context to the user and stop.
<!DOCTYPE html>
<html>
<body>
<form name="contact" data-netlify="true" netlify-honeypot="bot-field" hidden>
<input type="hidden" name="form-name" value="contact" />
<input type="text" name="name" />
<input type="email" name="email" />
<textarea name="message"></textarea>
<input name="bot-field" />
</form>
</body>
</html><form name="contact" method="POST" data-netlify="true">
<input type="hidden" name="form-name" value="contact" />
{/* ... fields ... */}
</form>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(),
});
});function ContactForm() {
const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
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 (
<form name="contact" method="POST" data-netlify="true" onSubmit={handleSubmit}>
<input type="hidden" name="form-name" value="contact" />
<input type="text" name="name" placeholder="Name" />
<input type="email" name="email" placeholder="Email" />
<textarea name="message" placeholder="Message" />
<button type="submit">Send</button>
</form>
);
}<form name="contact" method="POST" netlify-honeypot="bot-field" data-netlify="true">
<p style="display:none">
<label>Don't fill this out: <input name="bot-field" /></label>
</p>
<!-- visible fields -->
</form><form name="upload" enctype="multipart/form-data" data-netlify="true">
<input type="text" name="name" />
<input type="file" name="attachment" />
<button type="submit">Upload</button>
</form>await fetch("/", { method: "POST", body: new FormData(form) });GET /api/v1/forms/{form_id}/submissions
Authorization: Bearer <PERSONAL_ACCESS_TOKEN>