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.
npm install @seaforms/reactpnpm add @seaforms/reactyarn add @seaforms/reactbun add @seaforms/reactimport { 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.
What it draws
Section titled “What it draws”- 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.
What it sends
Section titled “What it sends”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.
Entry points
Section titled “Entry points”| 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
Section titled “getForm”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 pullsaves, 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.
The key
Section titled “The key”- In the app, go to Settings, then API keys. Only owners and admins of the workspace can make keys.
- Under Sites, choose the form’s site. Under It can, leave only Read forms ticked.
- Choose Make a key, and copy it. It’s shown once.
- Set it as
SEAFORMS_API_KEYwhere your site builds: your host’s environment variables, and a.envfile 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.
Options
Section titled “Options”getForm<T = FormDefinition>(formId: string, options: GetFormOptions): Promise<T>formIdstringrequiredThe form’s ID, such as
frm_7f3kq2m4xa: on its page in the app, under its name. See Your site and form IDs.apiKeystring | undefinedrequiredAn API key (
sfk_…) that can read forms on the form’s site. Passprocess.env.SEAFORMS_API_KEYas it is:undefinedstops the build with a message saying which key to make.fetchInitGetFormFetchInitPassed to
fetchas it is, for your framework’s caching: Next.js’snext: { revalidate, tags }, orcache. It’sRequestInitwithoutmethod,headers,bodyandredirect, whichgetFormsets itself.apistringAnother Seaforms server, for testing. Default
https://api.seaforms.io. The key only goes tohttps://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.
When it stops the build
Section titled “When it stops the build”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.
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. |
Content Security Policy
Section titled “Content Security Policy”If your site sends a Content-Security-Policy header, allow Seaforms’ two hosts:
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.
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