The Form component
import { Form } from "@seaforms/react";import contact from "./forms/contact.seaforms.json";
<Form schema={contact} onSubmitted={({ submissionId, ending }) => console.log(submissionId, ending)}/>;Form is a client component ("use client"), so a Next.js server component can render it as it is.
schemaFormDefinitionrequiredThe form’s file:
import contact from "./forms/contact.seaforms.json", or whatgetFormreturns. A file this version of the package can’t draw shows “This form needs an update to display” instead of a broken form: update@seaforms/react.classNamestringA class for the
<form>element.classNamesPartial<Record<Part, string>>Your classes, keyed by part:
{ input: "h-11 rounded-lg border px-3", "button-submit": "btn btn-primary" }. Every element also carriesdata-sf="<part>". See Styling.headingLevel2 | 3 | 4The heading level for step titles and thank-yous. Default
2. Use3when the form sits under your page’s own<h2>.testTokenstringA dev token (
sfd_…) from the app, for trying the form onlocalhost: answers are kept as tests, apart from real ones and never counted against your plan. Our server ignores it anywhere else. See Try it on your computer.onStep(change: { stepId, index, direction }) => voidThe visitor moved to another step.
directionis"forward"or"back".onError(errors: { stepId, fields }) => voidThe visitor tried to continue or send with answers that need fixing.
fieldslists their keys.onSubmitted(result: { submissionId, ending }) => voidThe answers were stored.
submissionIdis thesub_…ID,endingthe ID of the thank-you that showed. Called before any redirect the form’s settings make.staticbooleanFor a page that never loads the component’s script (Astro without a
client:directive). The form is drawn the way it works without JavaScript: every step on one page, one Send at the end. Leave it off when the form is hydrated. See Without JavaScript.instancestringOnly for two copies of the same form on one page: a suffix that keeps their element IDs apart, such as
instance="footer".apiBasestringWhere the form sends. Default
https://api.seaforms.io. You don’t need it.
The answers’ types
Section titled “The answers’ types”npx seaforms pull writes each form’s types beside its file, so the callbacks can be typed:
import type { ContactEnding, ContactStep } from "./forms/contact.seaforms";
<Form schema={contact} onStep={({ stepId }) => track(stepId as ContactStep)} onSubmitted={({ ending }) => ending as ContactEnding}/>;Analytics events
Section titled “Analytics events”The form fires five events, each a DOM event on the <form> (it bubbles) and a window.dataLayer push for Google Tag Manager. They carry IDs, never answers.
| DOM event | dataLayer event |
When | detail |
|---|---|---|---|
seaforms:view |
seaforms_view |
the form is on the page and awake | { formId, revision } |
seaforms:start |
seaforms_start |
the first answer | { formId, revision } |
seaforms:step |
seaforms_step |
each step change | { stepId, index, direction } |
seaforms:error |
seaforms_error |
an answer needs fixing | { stepId, fields } |
seaforms:submit |
seaforms_submit |
the answers were stored | { submissionId, ending } |
A dataLayer push puts the detail under seaforms. On Send it also pushes Google Analytics’ generate_lead, with the total and its currency when the form has a price.
document.addEventListener("seaforms:submit", (event) => { const { submissionId } = (event as CustomEvent<{ submissionId: string }>).detail;});Answers from the link
Section titled “Answers from the link”A question can be filled in from the page’s address, such as ?plan=pro, when the form’s builder turned that on for it. It’s filled in as the script starts, never over what the visitor already typed, and doesn’t count as them starting the form. Nothing to set on the component.
Save and finish later
Section titled “Save and finish later”When the form offers Save and finish later, the visitor can email themselves a link to their answers. The link opens your page with a key after #, and the form takes it out of the address bar the moment its script runs. So on every page the form is on, load its script with the page: in Astro, client:load, not client:visible.
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