Skip to content

The Form component

ContactPage.tsx
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.

schemaFormDefinitionrequired

The form’s file: import contact from "./forms/contact.seaforms.json", or what getForm returns. 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.

classNamestring

A 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 carries data-sf="<part>". See Styling.

headingLevel2 | 3 | 4

The heading level for step titles and thank-yous. Default 2. Use 3 when the form sits under your page’s own <h2>.

testTokenstring

A dev token (sfd_…) from the app, for trying the form on localhost: 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 }) => void

The visitor moved to another step. direction is "forward" or "back".

onError(errors: { stepId, fields }) => void

The visitor tried to continue or send with answers that need fixing. fields lists their keys.

onSubmitted(result: { submissionId, ending }) => void

The answers were stored. submissionId is the sub_… ID, ending the ID of the thank-you that showed. Called before any redirect the form’s settings make.

staticboolean

For 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.

instancestring

Only for two copies of the same form on one page: a suffix that keeps their element IDs apart, such as instance="footer".

apiBasestring

Where the form sends. Default https://api.seaforms.io. You don’t need it.

npx seaforms pull writes each form’s types beside its file, so the callbacks can be typed:

ContactPage.tsx
import type { ContactEnding, ContactStep } from "./forms/contact.seaforms";
<Form
schema={contact}
onStep={({ stepId }) => track(stepId as ContactStep)}
onSubmitted={({ ending }) => ending as ContactEnding}
/>;

See Types for your answers.

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.

analytics.ts
document.addEventListener("seaforms:submit", (event) => {
const { submissionId } = (event as CustomEvent<{ submissionId: string }>).detail;
});

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.

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.

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