--- name: netlify-forms description: Build and configure Netlify Forms for serverless form handling. Use when implementing contact forms, feedback forms, file uploads, or any form that collects user submissions without backend code. Make sure to always run `node scripts/enable.cjs` located in this skill's directory after implementing Netlify Forms. --- # Netlify Forms Netlify Forms is a serverless form-handling service. The build system parses HTML at deploy time to detect forms and automatically creates submission endpoints. ## Enable Feature After implementing Netlify Forms, you **must** run the enable script to activate the feature on the deploy. The script is located in this skill's `scripts/` directory: ```bash node scripts/enable.cjs ``` ## Quick Start Add `data-netlify="true"` or `netlify` attribute to any ` ``` **Key requirements:** - The `name` attribute identifies the form in Netlify UI (must be unique per site) - Method must be `POST` - Netlify injects a hidden `form-name` field during build ## AJAX / JavaScript Submission Submit forms without page reload: ```javascript const form = document.getElementById('contact-form') form.addEventListener('submit', async (e) => { e.preventDefault() const response = await fetch('/', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(new FormData(form)).toString(), }) if (response.ok) { // Handle success } }) ``` > **SSR/SPA apps (React, Vue, TanStack Start, Next.js, SvelteKit, Remix, Nuxt):** You MUST create a static HTML skeleton > file for build-time form detection. Without it, Netlify cannot detect the form during build and submissions will > silently fail. Additionally, the `fetch` URL must target the skeleton file path (e.g. `/__forms.html`), **not** `/` — > in SSR apps, `fetch('/')` is intercepted by the SSR function and never reaches Netlify's form processing middleware. > See [JavaScript Frameworks](#javascript-frameworks-ssr--client-rendered-apps) below. **Critical AJAX requirements:** 1. Content-Type MUST be `application/x-www-form-urlencoded` 2. Include hidden `form-name` field in your HTML: ```html ``` ## JavaScript Frameworks (SSR & Client-Rendered Apps) Netlify's build bot cannot detect forms rendered client-side. For any SSR or SPA framework (React, Vue, TanStack Start, Next.js, SvelteKit, Remix, Nuxt), you MUST: 1. **Create a static HTML skeleton** in `public/` for build-time form detection — this is the critical step. Without it, Netlify never registers the form and submissions will silently fail or 404. 2. Submit via AJAX with `e.preventDefault()` — full-page POST will not work in SPAs 3. Include a hidden `form-name` field matching the form's `name` attribute ### Static Form Skeleton Create a static HTML file (e.g. `public/__forms.html`) containing every form your app uses. The file name does not matter — Netlify scans all HTML files in the build output: ```html ``` **Rules:** - The form `name` attribute must exactly match the `form-name` value in your React/Vue component - Include every field your component submits — Netlify validates field names against the registered form - Add `netlify-honeypot="bot-field"` and a `bot-field` input for spam protection ### React Example ```jsx function ContactForm() { const handleSubmit = async (e) => { e.preventDefault() const formData = new FormData(e.target) // URL must point to the static skeleton file, not '/' — SSR catch-all intercepts '/' await fetch('/__forms.html', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(formData).toString(), }) } return (

{/* Hidden field required for AJAX */}

Don't fill this out:

<button type="submit">Send</button>
    </form>
  )
}
```

## File Uploads

```html
<form name="upload" method="POST" data-netlify="true" enctype="multipart/form-data">
  <input type="file" name="attachment" />
  <button type="submit">Upload</button>
</form>
```

**Limits:**

- Maximum request size: **8 MB**
- Timeout: **30 seconds**
- One file per input field (use multiple inputs for multiple files)

**Security:** For file uploads containing PII (personally identifiable information), use the
[Very Good Security (VGS)](https://www.netlify.com/integrations/very-good-security/) integration for additional
protection.

**AJAX file uploads:** Do NOT set Content-Type header - let browser set `multipart/form-data` with boundary:

```javascript
// Correct - no Content-Type header
fetch('/', {
  method: 'POST',
  body: new FormData(form), // Browser sets correct Content-Type
})
```

## Spam Protection

### Honeypot Field (Recommended)

```html
<form name="contact" method="POST" data-netlify="true" netlify-honeypot="bot-field">
  
  <p style="display:none">
    <label>Don't fill this: <input name="bot-field" /></label>
  </p>

<input name="name" required />
  <button type="submit">Send</button>
</form>
```

### reCAPTCHA v2 (Netlify-provided)

```html
<form name="contact" method="POST" data-netlify="true" data-netlify-recaptcha="true">
  <input name="name" required />

<div data-netlify-recaptcha="true"></div>

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

Only one Netlify-provided reCAPTCHA per page. For multiple CAPTCHAs on one page, use custom reCAPTCHA.

### Custom reCAPTCHA v2

Use your own reCAPTCHA 2 code with Netlify validation:

1. Sign up for a [reCAPTCHA API key pair](http://www.google.com/recaptcha/admin) and add the reCAPTCHA script/widget to
   your form.
2. Set environment variables in Netlify (UI, CLI, or API):
   - `SITE_RECAPTCHA_KEY` — your reCAPTCHA site key (scopes: Builds + Runtime)
   - `SITE_RECAPTCHA_SECRET` — your reCAPTCHA secret key (scope: Runtime)
3. Add `data-netlify-recaptcha="true"` to your `<form>` tag.

Netlify validates the `g-recaptcha-response` server-side on each submission.

**For AJAX with reCAPTCHA:** Include `g-recaptcha-response` in POST body (automatic if using `FormData()`).

## Success Redirects

```html

<form name="contact" method="POST" data-netlify="true" action="/thank-you"></form>
```

The `action` path must:

- Start with `/`
- Be relative to site root
- Point to an existing page

> **Pretty URLs:** Netlify serves `thank-you.html` at `/thank-you` by default. Use `action="/thank-you"`, not
> `action="/thank-you.html"` — the `.html` path returns 404.

## Notifications

### Email Notifications

Configure in Netlify UI: **Project configuration > Notifications > Emails and webhooks > Form submission notifications**

- Include `<input name="email">` to set reply-to address automatically
- Custom subject line:
  ```html
  <input type="hidden" name="subject" value="New inquiry from %{formName}" />
  ```
- Available variables: `%{formName}`, `%{siteName}`, `%{submissionId}`
- For forms created before May 5, 2023: remove `[Netlify]` prefix from subject by adding `data-remove-prefix`:
  ```html
  <input type="hidden" name="subject" data-remove-prefix value="Sales inquiry" />
  ```

### Webhooks

Configure in Netlify UI: **Project configuration > Notifications > Emails and webhooks > Form submission notifications**

Sends JSON payload on each verified submission.

## Function Triggers

Trigger serverless functions on submissions:

```typescript
// netlify/functions/submission-created.mts
import type { Context } from '@netlify/functions'

interface FormPayload {
  form_name: string
  data: Record<string, string>
  created_at: string
}

export default async (req: Request, context: Context) => {
  const { payload } = (await req.json()) as { payload: FormPayload }

console.log('Form:', payload.form_name)
  console.log('Data:', payload.data)

// Process submission (send to CRM, Slack, etc.)

return new Response('OK')
}
```

**Event name:** `submission-created` (filename must match)

## Limits

| Feature      | Free Tier   | Paid Tier  |
| ------------ | ----------- | ---------- |
| Submissions  | 100/month   | Metered    |
| File Storage | 10 MB/month | Scalable   |
| Request Size | 8 MB        | 8 MB       |
| Timeout      | 30 seconds  | 30 seconds |

## Common Errors & Solutions

### "404 on submit"

**Cause:** Build bot didn't detect the form. **Fix:**

1. Ensure static HTML version exists for JS frameworks
2. Verify `form-name` hidden input is present
3. Check form has `name` attribute

### Submissions not appearing

**Check:**

1. Look in **Spam** folder in Netlify UI (Akismet filtering)
2. Avoid test values like "test@test.com" or "asdf" — use real email and full sentences
3. Verify form was included in the latest deploy

### AJAX submission fails silently

**Ensure:**

1. Content-Type is `application/x-www-form-urlencoded` (not JSON)
2. `form-name` field is included in body
3. Check browser Network tab for actual response

### Form succeeds but no submissions appear (SSR apps)

**Cause:** Two things must be true for SSR form submissions to work:

1. A static HTML skeleton file must exist in `public/` so Netlify registers the form at build time.
2. The `fetch` URL must target the skeleton file path (e.g. `/__forms.html`), **not** `/`.

Without (1), Netlify doesn't know the form exists. Without (2), the POST to `/` is intercepted by the SSR catch-all
function (TanStack Start, Next.js, SvelteKit, Remix, Nuxt) — the SSR handler renders a 200 HTML page, so `fetch()`
reports success, but the request never reaches Netlify's form processing middleware.

**Fix:**

1. Create a static HTML skeleton in `public/` (see
   [JavaScript Frameworks](#javascript-frameworks-ssr--client-rendered-apps) section).
2. Change `fetch('/')` to `fetch('/__forms.html')` (or whatever path your skeleton file is at) so the request routes
   through the CDN origin where Netlify's `formsHandler` runs.

### File upload fails

**Check:**

1. Total request size under 8 MB
2. Not setting Content-Type header manually
3. Using `enctype="multipart/form-data"` on form

## API Access

List submissions programmatically:

```bash
curl -H "Authorization: Bearer $NETLIFY_AUTH_TOKEN" \
  https://api.netlify.com/api/v1/forms/{form_id}/submissions
```

Export available as CSV from Netlify UI.