Skip to content

Quickstart

You need Node 22 or later, a project on React 18.2 or later (Next.js, React Router in Framework mode, Astro, or React on its own), and a free Seaforms account at app.seaforms.io.

  1. Add your site in the app. Go to Settings, then Sites. Under A site built with code, choose Add it, give it a name and its address, such as https://northwind.co, and choose Add the site.

  2. Build a form and publish it. In Forms, choose New form. Start from a template, a description or a blank form, then choose Publish. Your code only ever sees published forms.

  3. Install the package in your project.

    Terminal window
    npm install @seaforms/react
  4. Sign in and pull your forms. From your project’s folder:

    Terminal window
    npx seaforms login
    npx seaforms pull

    login opens Seaforms in your browser to approve it. pull saves each published form of the site in src/forms (or forms when there’s no src), with its types beside it:

    Terminal window
    $ npx seaforms pull
    Northwind's forms, into src/forms:
    ✔ contact revision 3, saved
    Rebuild and deploy your site to put the change on its pages.

    The first time, it asks which site this project is (or picks your only one) and saves the answer in seaforms.json. Commit seaforms.json and the form files.

  5. Show the form on a page.

    app/contact/page.tsx
    import { Form } from "@seaforms/react";
    import contact from "@/forms/contact.seaforms.json";
    export default function ContactPage() {
    return (
    <main>
    <h1>Get in touch</h1>
    <Form schema={contact} />
    </main>
    );
    }

    Form is a client component, so a server page can use it as it is. Next.js renders it into the page’s HTML.

  6. Add your site’s addresses. In the app, go to Settings, then Site details, and add every address the site is served from under Addresses, such as https://northwind.co and https://www.northwind.co.

    A submission from an address that isn’t on the list is still kept, but as spam, so a copied form can’t fill your inbox.

  7. Try it on your computer. Make a dev token under Dev tokens in Site details, and pass it while you work:

    Your page
    <Form schema={contact} testToken="sfd_…" />

    On localhost, answers sent with it are tests: kept apart from real ones and never counted against your plan. See Try it on your computer.

src/forms/contact.seaforms.json holds the form’s questions, steps and logic. You never edit it: change the form in the app, publish, and pull again.

src/forms/contact.seaforms.json
{
"schemaVersion": 1,
"id": "frm_7f3kq2m4xa",
"revision": 3,
"locale": "en-AU",
"timezone": "Australia/Adelaide",
"presentation": {
"mode": "steps",
"progress": {
"bar": false,
"time": true
},
"labels": {
"next": "Continue",
"back": "Back",
"submit": "Send message"
},
"estimatedSeconds": 60,
"requiredMarker": "optional-label",
"badge": false
},
"steps": [
{
"id": "get-in-touch",
"title": "Get in touch",
"blocks": [
{
"kind": "field",
"key": "name",
"label": "Name",
"placeholder": "Maya Chen",
"required": true,
"autocomplete": "name",
"type": "text"
},
{
"kind": "field",
"key": "email",
"label": "Email",
"placeholder": "maya@northwind.co",
"required": true,
"autocomplete": "email",
"type": "email"
},
{
"kind": "field",
"key": "topic",
"label": "What’s it about?",
"required": true,
"type": "choice",
"display": "chips",
"options": [
{
"value": "sales",
"label": "Sales"
},
{
"value": "support",
"label": "Support"
},
{
"value": "press",
"label": "Press"
},
{
"value": "something-else",
"label": "Something else"
}
]
},
{
"kind": "field",
"key": "message",
"label": "Message",
"placeholder": "How can we help?",
"required": true,
"type": "textarea"
}
]
}
],
"endings": [
{
"id": "thanks",
"title": "Thanks, {name}.",
"body": "Your message is with the right person. We usually reply the same day."
}
],
"features": [],
"initial": {
"hidden": [],
"alwaysRequired": [
"name",
"email",
"topic",
"message"
]
},
"hash": "3096824560e56c78"
}
  • Next.js, React Router or Astro: fetch the form while your site builds instead, so a client’s publish needs no pull.
  • Styling: your own classes, or our finished look.
  • Webhooks: each submission at your own endpoint.
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