Skip to content

Install the React package

@seaforms/react draws a published Seaforms form as part of your page. It needs React 18.2 or later, and works in anything that renders React: Next.js, Astro with its React integration, React Router in Framework mode, Remix, or a plain React app.

Terminal window
npm install @seaforms/react
ContactPage.tsx
import { Form } from "@seaforms/react";
import contact from "./forms/contact.seaforms.json";
<Form schema={contact} />;

schema is the form’s file, pulled with npx seaforms pull or fetched while your site builds with getForm.

  • A real HTML form, on your server. It’s in the page’s HTML before any JavaScript loads, with a real <form action> that posts to Seaforms if scripts never run. See Without JavaScript.
  • Then it wakes up. Once its script runs: one step at a time with Continue and Back, questions that appear as they’re answered, errors when they help (when the visitor tries to continue, or leaves a field with a mistake in it), a live price, file uploads, payments and booking.
  • Nothing moves. Every step, error line and price line has its room from the first render, so waking up shifts nothing on the page.
  • Keyboard and screen readers. Enter moves on. Focus goes to the new step’s title, or to the first answer that needs fixing, and both are announced. Anything typed before JavaScript loaded is kept.

Nothing is requested from Seaforms until the visitor first touches the form. Then it opens a session with https://api.seaforms.io, uploads files as they’re picked, and on Send stores the answers and shows the thank-you in the form’s own space. A dropped connection is retried, and one session stores at most one submission, so a retry never sends twice.

Our server checks every answer again against the form, so a visitor can’t skip a required question or change a price by editing the page.

Import What it is
@seaforms/react Form, the component, and Parts, the names of every part you can style.
@seaforms/react/server getForm, for code that runs while your site builds. It isn’t in the main entry, so it never reaches a browser bundle.
@seaforms/react/theme.css Our optional finished look. See Styling.

getForm fetches a form’s latest published version while your site builds, for forms a client or colleague edits. The code for your framework is on the Next.js, React Router and Astro pages.

  • The same form as the file. It returns exactly what the form’s file holds, byte for byte what npx seaforms pull saves, so the form draws the same either way.
  • Still in your page’s HTML. It runs while the site builds. Nothing is fetched while a visitor’s page loads.
  • It stops the build rather than ship a page without its form. Every problem is a plain message in your build log.
  1. In the app, go to Settings, then API keys. Only owners and admins of the workspace can make keys.
  2. Under Sites, choose the form’s site. Under It can, leave only Read forms ticked.
  3. Choose Make a key, and copy it. It’s shown once.
  4. Set it as SEAFORMS_API_KEY where your site builds: your host’s environment variables, and a .env file you don’t commit for your own computer.

A key for one site can’t see any other, and one that can only read forms can’t change anything. Never put the key in your code, and never in anything a browser loads: getForm refuses to run where window exists.

getForm
getForm<T = FormDefinition>(formId: string, options: GetFormOptions): Promise<T>
formIdstringrequired

The form’s ID, such as frm_7f3kq2m4xa: on its page in the app, under its name. See Your site and form IDs.

apiKeystring | undefinedrequired

An API key (sfk_…) that can read forms on the form’s site. Pass process.env.SEAFORMS_API_KEY as it is: undefined stops the build with a message saying which key to make.

fetchInitGetFormFetchInit

Passed to fetch as it is, for your framework’s caching: Next.js’s next: { revalidate, tags }, or cache. It’s RequestInit without method, headers, body and redirect, which getForm sets itself.

apistring

Another Seaforms server, for testing. Default https://api.seaforms.io. The key only goes to https:// addresses, or to this computer.

It asks for the form’s latest published revision, waits up to 30 seconds, and tries once more when Seaforms is out of reach, slow, busy or briefly down. It never follows a redirect, and the key is never in an error message.

Each problem throws a SeaformsError with a code and a message worded for a build log. status is the HTTP status Seaforms answered with, or 0.

Handling a SeaformsError
import { getForm, SeaformsError } from "@seaforms/react/server";
try {
return await getForm("frm_7f3kq2m4xa", { apiKey: process.env.SEAFORMS_API_KEY });
} catch (e) {
if (e instanceof SeaformsError && e.code === "not_published") return null;
throw e;
}
code What happened
no_key No key was given.
dev_token It was given a dev token (sfd_…), which is only for localhost.
bad_key The key has a space or a line break in it: copy it again.
bad_id The ID isn’t a form’s ID, or the key was passed where the ID goes.
browser It ran where window exists. Call it where your site builds.
unsafe_address api isn’t https://, or has a user name or password in it.
unauthenticated Seaforms didn’t accept the key: revoked, or copied only in part.
forbidden The key can’t read forms.
workspace_closed The workspace was deleted. For 7 days an owner can restore it.
not_found No form with that ID that this key can see: check the key’s site.
not_published The form hasn’t been published yet.
cant_draw A newer Seaforms published it than this package can draw: update @seaforms/react.
rate_limited Too many requests with this key. Wait a minute.
unavailable, network, timeout Seaforms couldn’t be reached, after one more try.
redirect Something answered with a redirect, which isn’t followed.
unreadable, refused Seaforms sent something unexpected, or refused for another reason.

If your site sends a Content-Security-Policy header, allow Seaforms’ two hosts:

Content-Security-Policy
connect-src 'self' https://api.seaforms.io;
frame-src 'self' https://forms.seaforms.io;

api.seaforms.io takes the answers and files. forms.seaforms.io holds the human check, a small frame that’s invisible unless Cloudflare asks the visitor for a click.

A form that takes a payment also loads Stripe’s own card fields. Add what Stripe’s Content Security Policy guide lists for Stripe.js.

Was this helpful?

Your answer goes straight to the person who wrote it.

Thanks. We read every note and update the article.

Thanks, that helps us keep these useful.

ChatGPT is a trademark of OpenAI, and Claude and Claude Code are trademarks of Anthropic. Other product names and logos belong to their owners. None of them makes or endorses Seaforms. Trademarks