Skip to content

Next.js ​

A BootForm form is a plain HTML form, so it needs no Server Action, no API route and no SDK. The examples use the App Router and TypeScript, as create-next-app sets them up, and were built with Next.js 16. They work on a static export too, so the site can be hosted on GitHub Pages.

Basic form ​

Put the form in a page, for example app/contact/page.tsx. This is a Server Component, and the form works with JavaScript turned off:

tsx
export default function ContactPage() {
  return (
    <form action="https://f.bootform.com/{form_id}" method="POST">
      <label htmlFor="email">Your email</label>
      <input id="email" name="email" type="email" required />
      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" required />
      {/* Required: BootForm's spam trap. Keep this hidden field and leave it empty. */}
      <input type="text" name="honeypot" style={{ position: 'absolute', left: '-9999px' }} tabIndex={-1} autoComplete="off" aria-hidden="true" />
      <button type="submit">Send</button>
    </form>
  )
}

Because action is a URL string, Next.js renders an ordinary HTML form and the browser posts it straight to BootForm. Only a function passed to action becomes a Server Action.

Replace {form_id} with a UUID you generate yourself (the UUID generator gives you one). Send yourself a test message, then claim the form before the site goes live, so nobody else can claim your ID first.

The honeypot field is a spam trap: people never see it, bots fill it in. Keep it positioned off screen as shown, not hidden with hidden or display: none. New forms use the name honeypot; if you renamed yours, use the name in your form's snippet. See Spam protection.

Keep the form ID in an environment variable ​

The form ID is public, since it is in the page's HTML anyway, so it can live in a NEXT_PUBLIC_ variable. Create .env.local in the project root:

bash
NEXT_PUBLIC_BOOTFORM_FORM_ID={form_id}

Then move the form into one component, components/ContactForm.tsx, and read the ID there:

tsx
const formId = process.env.NEXT_PUBLIC_BOOTFORM_FORM_ID

export default function ContactForm() {
  return (
    <form action={`https://f.bootform.com/${formId}`} method="POST">
      {/* The same fields as in the basic form, honeypot included. */}
    </form>
  )
}

Use it on any page:

tsx
import ContactForm from '@/components/ContactForm'

export default function ContactPage() {
  return <ContactForm />
}

Next.js reads .env.local when it starts and writes the value into the page at build time. Restart next dev, or build again, after you change it.

create-next-app adds .env* to .gitignore, so .env.local never reaches a build that runs somewhere else, such as GitHub Actions. Set the same variables there, as env on the build step.

The BootForm API key is a different thing: it is a secret, and this guide never needs it. Never put it in a NEXT_PUBLIC_ variable or a Client Component.

A thank-you page ​

By default, a successful submission shows the visitor BootForm's short "Thanks" page. To send them to a page of your own instead, create it as app/thanks/page.tsx:

tsx
export default function ThanksPage() {
  return <p>Thanks, your message is on its way. Expect a reply within a day.</p>
}

Then add a hidden _redirect field with the page's full URL. In components/ContactForm.tsx, build the URL above the component:

tsx
const thanksUrl = `${process.env.NEXT_PUBLIC_SITE_URL}${process.env.NEXT_PUBLIC_BASE_PATH ?? ''}/thanks`

and add the field inside the <form>:

tsx
<input type="hidden" name="_redirect" value={thanksUrl} />

The redirect has to be on the same site as the form, or on one of the form's allowed origins. Any other URL is ignored.

Set the two variables in .env.local. On GitHub Pages a project site (anything but yourname.github.io itself) is served from a subpath, which Next.js calls basePath:

bash
NEXT_PUBLIC_SITE_URL=https://yourname.github.io
NEXT_PUBLIC_BASE_PATH=/your-repo-name

Use the same variable in next.config.ts, so the config and the form always agree:

ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  basePath: process.env.NEXT_PUBLIC_BASE_PATH,
}

export default nextConfig

The built field is then value="https://yourname.github.io/your-repo-name/thanks". On your own domain, set NEXT_PUBLIC_SITE_URL to it and leave NEXT_PUBLIC_BASE_PATH out.

Sending without leaving the page ​

To submit in the background and show a message in place, the form needs state and an event handler, so it has to be a Client Component. Replace components/ContactForm.tsx with this. The fetch and its error handling are the same as in the React guide:

tsx
'use client'

import { useState, type FormEvent } from 'react'

const formId = process.env.NEXT_PUBLIC_BOOTFORM_FORM_ID

export default function ContactForm() {
  const [status, setStatus] = useState<'idle' | 'sending' | 'sent' | 'error'>('idle')
  const [error, setError] = useState<string | null>(null)

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const form = event.currentTarget
    setStatus('sending')

    try {
      const response = await fetch(form.action, {
        method: 'POST',
        headers: { Accept: 'application/json' },
        body: new FormData(form),
      })
      const result = await response.json()

      if (result.ok) {
        form.reset()
        setStatus('sent')
      } else {
        setError(result.error)
        setStatus('error')
      }
    } catch {
      setError('Could not send. Check your connection and try again.')
      setStatus('error')
    }
  }

  return (
    <form action={`https://f.bootform.com/${formId}`} method="POST" onSubmit={handleSubmit}>
      <label htmlFor="email">Your email</label>
      <input id="email" name="email" type="email" required />
      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" required />
      {/* Required: BootForm's spam trap. Keep this hidden field and leave it empty. */}
      <input type="text" name="honeypot" style={{ position: 'absolute', left: '-9999px' }} tabIndex={-1} autoComplete="off" aria-hidden="true" />
      <button type="submit" disabled={status === 'sending'}>
        {status === 'sending' ? 'Sending…' : 'Send'}
      </button>
      {status === 'sent' && <p role="status">Thanks, your message was sent.</p>}
      {status === 'error' && <p role="alert">{error}</p>}
    </form>
  )
}

The page that imports it stays a Server Component and doesn't change. Leave _redirect out here; it only applies to a classic form post.

Static export ​

To host the site on GitHub Pages or any other static host, add one line to the config above. next build then writes plain HTML files to out/:

ts
const nextConfig: NextConfig = {
  output: 'export',
  basePath: process.env.NEXT_PUBLIC_BASE_PATH,
}

Both versions of the form work the same on an export, because the browser posts to BootForm and nothing runs on your host. The thank-you page is written as out/thanks.html, which GitHub Pages serves at /thanks. If your host needs a folder instead, add trailingSlash: true (the file becomes out/thanks/index.html) and end the _redirect URL with /thanks/. See also Contact form on GitHub Pages.

Pages Router ​

Two things differ. Pages live in pages/ (pages/contact.tsx, pages/thanks.tsx). And there are no Server Components, so the 'use client' line isn't needed, though leaving it in does no harm. The environment variables, _redirect and static export are the same.

File uploads and the moderated feed ​

Both are the components from the React guide, unchanged: see React, file upload and React, moderated content feed. Each one uses state, so add 'use client' as the first line of its file. A file upload needs the form claimed first.

Common problems ​

The built form's action ends in /undefined. NEXT_PUBLIC_BOOTFORM_FORM_ID wasn't set when the site was built. The build doesn't fail or warn. Check the name, restart next dev, and set the variable wherever the site is built, since .env.local is not in git.

After sending, the visitor lands on a 404, or on BootForm's page instead of yours. The _redirect URL is wrong. A missing repository name means NEXT_PUBLIC_BASE_PATH isn't set; a value starting with undefined means NEXT_PUBLIC_SITE_URL isn't. Open the built page's source and check the field's value.

The build fails with "Event handlers cannot be passed to Client Component props", or says useState "is only available in Client Components". The form has an onSubmit or state, but its file is a Server Component. Add 'use client' as the first line of the form's file.

The build fails with "PPR cannot be enabled in export mode". Your next.config.ts has cacheComponents: true, which create-next-app can add. It can't be combined with output: 'export'. Remove it, and partialPrefetching with it.

npm run lint reports react/no-unescaped-entities. There is an apostrophe in the text of a page, such as "We'll reply". Write &apos; instead, or reword the sentence.

You sent a test message but no email arrived. The form isn't claimed yet. Nothing is delivered until it is; claim it and the messages sent so far are delivered. Held messages are kept for 48 hours.