Next.js

The component keeps the fields in state, posts them as JSON and shows formcarry’s answer, and the same request carries files, a spam blocker token and validation errors, from the browser or from a Server Action.

Prerequisites

Before you start, you need:

A formcarry account. Sign up is free.
A form in the dashboard. Its endpoint is on the form’s Setup page. The examples use https://formcarry.com/s/AbC123xyz; put yours in its place.

The component

To send a form from the App Router, mark the file as a client component, post the fields as JSON, and send Accept: application/json so the answer comes back as JSON:

"use client"

import { useState } from "react"

export default function ContactForm() {
  const [fields, setFields] = useState({ email: "", message: "" })
  const [sent, setSent] = useState(false)
  const [error, setError] = useState("")

  function update(e) {
    setFields({ ...fields, [e.target.name]: e.target.value })
  }

  async function submit(e) {
    e.preventDefault()
    const res = await fetch("https://formcarry.com/s/AbC123xyz", {
      method: "POST",
      headers: { "Accept": "application/json", "Content-Type": "application/json" },
      body: JSON.stringify(fields),
    })
    const data = await res.json()
    if (data.code === 200) setSent(true)
    else setError(data.message)
  }

  if (sent) return <p>Thanks, we got your message.</p>

  return (
    <form onSubmit={submit}>
      <input name="email" type="email" value={fields.email} onChange={update} />
      <textarea name="message" value={fields.message} onChange={update} />
      <button type="submit">Send</button>
      {error && <p>{error}</p>}
    </form>
  )
}

The keys of the JSON body are the field names formcarry stores. The email key is the visitor’s address, so it becomes the reply-to address of your notification email and the recipient of the auto response. A stored submission answers with code: 200. A refused one answers with the reason in message, see What every form needs.

The same request with Axios is on the React page.

Put "use client" on the first line rather than leaving it out, otherwise the App Router renders the file as a Server Component, where useState is not available. In the Pages Router the same component works without that line. To read the endpoint from the environment instead of the source, put it in .env.local with the NEXT_PUBLIC_ prefix:

NEXT_PUBLIC_FORMCARRY_ENDPOINT=https://formcarry.com/s/AbC123xyz

Then read it in the component:

const res = await fetch(process.env.NEXT_PUBLIC_FORMCARRY_ENDPOINT, {
  method: "POST",
  headers: { "Accept": "application/json", "Content-Type": "application/json" },
  body: JSON.stringify(fields),
})

Name it NEXT_PUBLIC_FORMCARRY_ENDPOINT rather than FORMCARRY_ENDPOINT, otherwise the browser reads undefined and the request never reaches formcarry. Next.js inlines only NEXT_PUBLIC_ variables into the browser bundle, and this request runs in the browser.

Files

To send files, build a FormData from the form element in the client component and leave the content type to the browser:

async function submit(e) {
  e.preventDefault()
  const res = await fetch("https://formcarry.com/s/AbC123xyz", {
    method: "POST",
    headers: { "Accept": "application/json" },
    body: new FormData(e.currentTarget),
  })
  const data = await res.json()
}

Every input needs a name, including the file input, because FormData reads them by name. Send Accept and nothing else rather than adding Content-Type yourself, otherwise the multipart boundary is missing and the upload fails. For several files, or for File objects that a dropzone library hands you, append each one under its own name:

const data = new FormData()
data.append("email", fields.email)
files.forEach((file, i) => data.append(`file-${i}`, file, file.name))

For small files you can stick with JSON and send the file as a data URL. Read it with FileReader, and give each file its own key (never an array):

const toDataUrl = (file) =>
  new Promise((resolve, reject) => {
    const reader = new FileReader()
    reader.onload = () => resolve(reader.result)
    reader.onerror = reject
    reader.readAsDataURL(file)
  })

body: JSON.stringify({ ...fields, attachment: await toDataUrl(file) })

Use data URLs for small files. Using them with larger files bloats the request by about a third and reaches the 50 MB limit sooner.

Files are stored on paid plans only. Free plans store the rest of the submission without them.

Server Action

A Server Action posts from your server, so the endpoint stays out of the browser bundle. Put the endpoint in .env.local without the prefix:

FORMCARRY_ENDPOINT=https://formcarry.com/s/AbC123xyz

Put the request in a file marked "use server":

// app/actions.js
"use server"

export async function sendContact(fields) {
  const res = await fetch(process.env.FORMCARRY_ENDPOINT, {
    method: "POST",
    headers: { "Accept": "application/json", "Content-Type": "application/json" },
    body: JSON.stringify(fields),
  })
  return res.json()
}

Then call the action from the client component in place of fetch:

"use client"

import { sendContact } from "./actions"

async function submit(e) {
  e.preventDefault()
  const data = await sendContact(fields)
  if (data.code === 200) setSent(true)
  else setError(data.message)
}

The action runs on the server, so its variable doesn’t need the NEXT_PUBLIC_ prefix. The endpoint is not a secret. Any HTML form that posts to it already shows the endpoint in its action, so posting from the server doesn’t make it any safer. Because of this, every submission now leaves from your server’s IP address. The rate limit (1 submission per 15 seconds per form per IP address) applies to all of your visitors together as one shared limit. If two users submit within 15 seconds of each other, the second gets a 429. The spam blocker token is still produced in the browser, so the client component still renders the challenge and passes the token to the action.

We recommend posting from the browser for public forms. The limit then applies to each visitor on their own, giving them their own 15-second window.

Spam blocker

To add a challenge, render its widget in the client component, send the token under the name formcarry reads, and paste the secret key into the form’s settings under Form Security:

Challenge	Package the React demo uses	Token field
reCAPTCHA v2	`react-google-recaptcha`	`g-recaptcha-response`
reCAPTCHA v3	`react-google-recaptcha-v3`	`g-recaptcha-response`
hCaptcha	`@hcaptcha/react-hcaptcha`	`h-captcha-response`
Turnstile	`@marsidev/react-turnstile`	`cf-turnstile-response`

With reCAPTCHA v2, put the site key in .env.local as NEXT_PUBLIC_RECAPTCHA_SITE_KEY, read it the same way as the endpoint, and send nothing while the token is empty:

import ReCAPTCHA from "react-google-recaptcha"

const [token, setToken] = useState("")

<ReCAPTCHA sitekey={process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY} onChange={setToken} />

async function submit(e) {
  e.preventDefault()
  if (!token) {
    setError("Complete the challenge first")
    return
  }
  const res = await fetch(process.env.NEXT_PUBLIC_FORMCARRY_ENDPOINT, {
    method: "POST",
    headers: { "Accept": "application/json", "Content-Type": "application/json" },
    body: JSON.stringify({ ...fields, "g-recaptcha-response": token }),
  })
}

With reCAPTCHA v3 there is no widget. Wrap the form in the provider, call executeRecaptcha() when the visitor submits, and send what it returns:

"use client"

import { GoogleReCaptchaProvider, useGoogleReCaptcha } from "react-google-recaptcha-v3"

export default function ContactPage() {
  return (
    <GoogleReCaptchaProvider reCaptchaKey={process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY}>
      <ContactForm />
    </GoogleReCaptchaProvider>
  )
}

function ContactForm() {
  const { executeRecaptcha } = useGoogleReCaptcha()

  async function submit(e) {
    e.preventDefault()
    const token = await executeRecaptcha("contact")
    const res = await fetch(process.env.NEXT_PUBLIC_FORMCARRY_ENDPOINT, {
      method: "POST",
      headers: { "Accept": "application/json", "Content-Type": "application/json" },
      body: JSON.stringify({ ...fields, "g-recaptcha-response": token }),
    })
  }
}

With hCaptcha, the widget passes the token to onVerify:

import HCaptcha from "@hcaptcha/react-hcaptcha"

<HCaptcha sitekey={process.env.NEXT_PUBLIC_HCAPTCHA_SITE_KEY} onVerify={setToken} />

body: JSON.stringify({ ...fields, "h-captcha-response": token })

With Turnstile, to onSuccess:

import { Turnstile } from "@marsidev/react-turnstile"

<Turnstile siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY} onSuccess={setToken} />

body: JSON.stringify({ ...fields, "cf-turnstile-response": token })

When the post goes through a Server Action, the widget stays in the client component and the token travels with the fields:

const data = await sendContact({ ...fields, "g-recaptcha-response": token })

The widgets run in the browser, so they render in a client component whichever way you post. Refuse to send while the token is empty rather than posting anyway, otherwise formcarry answers 403 for reCAPTCHA and 400 for the others. Add localhost to the challenge’s allowed domains while you test.

Validation errors

A 422 carries errors, one entry per failing field, each with a message. To show each one next to its field, keep errors in state and check for 422 before the general error:

const [fieldErrors, setFieldErrors] = useState({})

const data = await res.json()
if (data.code === 200) setSent(true)
else if (data.code === 422) setFieldErrors(data.errors)
else setError(data.message)

{fieldErrors.email && <p>{fieldErrors.email.message}</p>}

It works through the Server Action too, because the action returns formcarry’s answer unchanged:

const data = await sendContact(fields)
if (data.code === 422) setFieldErrors(data.errors)

What’s next

Field validations: the rules you can set per field.
Spam protection: the challenges, the filter and the honeypot.
Email notifications: the auto response the visitor gets, keyed on email.

Stuck? Write to help@formcarry.com. Include the form id.

Getting Started

Features

Email Configuration

Integrations

Frameworks

Site builders

Build with AI

Connect over MCP

Prerequisites

The component

Files

Server Action

Spam blocker

Validation errors

What’s next

​Prerequisites

​The component

​Files

​Server Action

​Spam blocker

​Validation errors

​What’s next

Prerequisites

The component

Files

Server Action

Spam blocker

Validation errors

What’s next