Use defineForm() to define a typed form in Vue, Svelte, plain HTML, or React. In React, you can use one Fillo.* JSX component per question instead. Both versions create the same schema, and this guide shows them side by side. The JSX components define the form; they do not render its fields.
React: define forms in a client module. This applies only to <Fillo.Form> JSX. Add "use client" at the top of the file. Pass the compiled form across server and client boundaries, not the JSX.
The whole form
"use client";
import { Fillo, createClient, when } from "@usefillo/react";
import "@usefillo/react/styles.css";
const client = createClient({ key: process.env.NEXT_PUBLIC_FILLO_KEY! });
export function ContactForm() {
return (
<Fillo.Form id="contact" title="Talk to us" client={client}>
<Fillo.Text id="name" label="Your name" required />
<Fillo.Email id="email" label="Work email" required />
<Fillo.Select id="topic" label="What is this about?" required>
<Fillo.Option id="support" label="Support" />
<Fillo.Option id="sales" label="Sales" />
</Fillo.Select>
<Fillo.Text id="company" label="Company" visibleIf={when("topic").eq("sales")} />
<Fillo.LongText id="message" label="How can we help?" />
</Fillo.Form>
);
}when is exported by @usefillo/core (a dependency of both @usefillo/react and @usefillo/dom, though @usefillo/dom doesn't re-export it — import it from @usefillo/core directly alongside defineForm/createClient from @usefillo/dom).
Rules that keep the schema stable
Rules 2 and 5 apply to every framework. Rules 1, 3, and 4 apply only to JSX.
- Client module (JSX only). Define forms in a client module (
"use client"). JSX elements don't survive a server/client boundary. Pass the compiled value across it, never the JSX. - Ids are permanent (every form). Ids key responses, logic, piping, and sync. Never rename casually, never derive from position or a loop counter.
- Conditional questions are
visibleIf={when(…)…}, never{cond && <Fillo.…/>}(JSX only — params forms are static objects, not re-evaluated per render). Branching the JSX makes a per-visitor schema, which churns drafts in your workspace. A dev warning fires when a form's structure changes between renders. - Reuse is a plain function returning elements (JSX only), called inline as
{contactFields()}. Wrapper components are invisible to the compiler (children are never rendered) and throw. - You can always use
defineForm()(every form). JSX compiles to the same schema. Use the version that is easier to read in your project.
Multi-page forms
Wrap blocks in <Fillo.Page> elements. Children are either all pages or all blocks; mixing throws jsx-page_mix. Blocks without pages become one implicit page.
<Fillo.Form id="onboarding" title="Get set up" client={client}>
<Fillo.Page id="you" title="About you">
<Fillo.Text id="name" label="Full name" required />
<Fillo.Email id="email" label="Work email" required />
</Fillo.Page>
<Fillo.Page id="team" title="Your team">
<Fillo.Number id="seats" label="How many seats?" min={1} />
<Fillo.Checkbox id="invite" label="Email my team an invite" />
</Fillo.Page>
</Fillo.Form>Page jumps and early exit
Give a page a next array to branch the flow. Each { when, to } rule sends the respondent to another page ID or to "end". Conditions use the same when() model as visibleIf and combine with AND.
Rules run in order and the first match wins. Without a match, the next page opens. Skipped pages are not required and their answers are left out of the submission. Add routing in defineForm() or in the builder's Skip logic editor; <Fillo.Page> does not take routing props.
import { when } from "@usefillo/core";
// A page's `next` rules decide where the form goes after that page. Rules run
// top-to-bottom; the first whose conditions all match wins. `to` is another
// page's id, or "end" to finish the form early. No rule matches → the next
// page as usual. Conditions reuse when() — the same model as visibleIf.
const triage = defineForm({
id: "triage",
pages: [
{ id: "start", blocks: [
{ id: "kind", kind: "select", label: "What do you need?", options: [
{ id: "bug", label: "Report a bug" },
{ id: "praise", label: "Say something nice" },
]},
],
next: [
// Praise skips the repro page and ends right here:
{ when: [when("kind").eq("praise")], to: "end" },
],
},
{ id: "repro", blocks: [
{ id: "steps", kind: "long_text", label: "Steps to reproduce", required: true },
]},
{ id: "contact", blocks: [
{ id: "email", kind: "email", label: "Email for updates" },
]},
],
});
// "Report a bug" flows start → repro → contact and MUST answer steps.
// "Say something nice" ends after the first page — steps is never required,
// and a submission that skipped it validates fine on both client and server.Conditional questions: when()
when("fieldId") builds visibleIf conditions as plain data. Pass one condition or an array. Conditions in one array use AND; there is no OR operator. In the schema, visibleIf is always an array, even for one condition.
| Builder | Shows the field when |
|---|---|
| when("id").eq(value) | The answer equals value (any selected option in a multi-select). |
| when("id").neq(value) | The answer differs from value. Unanswered never satisfies neq. |
| when("id").contains(value) | Text contains value (case-insensitive), or a multi-select includes it. |
| when("id").gt(n) | A numeric answer is greater than n. |
| when("id").lt(n) | A numeric answer is less than n. |
| when("id").answered() | The field has any answer. |
| when("id").notAnswered() | The field has no answer yet. |
import { when } from "@usefillo/react";
// ✅ conditional questions are schema data:
<Fillo.LongText
id="unclear"
label="What was unclear?"
visibleIf={when("vote").eq("down")}
/>
// Multiple conditions AND together:
<Fillo.Text
id="phone"
label="Phone"
visibleIf={[when("topic").eq("sales"), when("seats").gt(50)]}
/>
// ❌ never branch the JSX — a per-visitor schema churns drafts
// in your workspace (a dev warning fires):
{topic === "sales" && <Fillo.Text id="company" label="Company" />}Options: children or prop
Choice fields accept <Fillo.Option> children or an options prop. Do not use both at once. The option ID is stored with each answer, so keep it stable. With defineForm(), use the options array.
// As children — reads best inline:
<Fillo.Select id="plan" label="Plan" required>
<Fillo.Option id="hobby" label="Hobby" />
<Fillo.Option id="team" label="Team" />
</Fillo.Select>
// As a prop — best when the list already exists as data:
const PLANS = [
{ id: "hobby", label: "Hobby" },
{ id: "team", label: "Team" },
];
<Fillo.Select id="plan" label="Plan" required options={PLANS} />Reuse without wrappers
Reuse fields with a function or array that returns blocks. Do not wrap fields in another React component.
// ✅ reuse is a plain function returning elements, called inline:
function contactFields() {
return (
<>
<Fillo.Text id="name" label="Your name" required />
<Fillo.Email id="email" label="Work email" required />
</>
);
}
<Fillo.Form id="contact" client={client}>
{contactFields()}
<Fillo.LongText id="message" label="Message" />
</Fillo.Form>;
// ❌ a wrapper component — <Fillo.Form> never renders children,
// so <ContactFields /> is invisible to the compiler and throws:
<Fillo.Form id="contact" client={client}>
<ContactFields />
</Fillo.Form>;Compile at module scope + headless
Fillo.defineForm(<Fillo.Form …/>) returns the same CodeForm value as defineForm(). Render it with <FilloForm>, build a custom React layout with <FilloProvider>, or use createFormController() in another framework.
"use client";
import { Fillo, FilloForm, FilloProvider, FormField, createClient } from "@usefillo/react";
const client = createClient({ key: "pk_…" });
// Compile once at module scope. The result is a plain CodeForm —
// the same value defineForm() returns.
const feedback = Fillo.defineForm(
<Fillo.Form id="feedback" title="Feedback">
<Fillo.Rating id="score" label="How was it?" max={5} required />
<Fillo.LongText id="notes" label="Tell us more" />
</Fillo.Form>,
);
// Render it framed…
<FilloForm form={feedback} client={client} />;
// …or headless, in your own layout:
<FilloProvider form={feedback} client={client}>
<FormField id="score" />
<FormField id="notes" />
</FilloProvider>;Headless registration. syncForm() is plain HTTP, so it also runs with no browser at all: call it from any Node process — a deploy hook, CI, a server route — to register the form in your workspace and get back { formId, status, warning }, no render involved. The compiler behind Fillo.defineForm() is React-free by design (codeFormFromJsx() / schemaFromJsx(), exported by @usefillo/core), so compiling and syncing JSX-authored forms never needs a DOM. Keep the form in one shared module that both your app and the sync script import; then the form your visitors see and the schema you sync can never drift.
// scripts/sync-forms.ts — node/tsx in CI or a deploy hook. No browser, no render.
import { createClient } from "@usefillo/core";
import { feedback } from "../src/forms/feedback"; // the same module your app renders
const client = createClient({ key: process.env.FILLO_KEY! });
const { formId, status, warning } = await client.syncForm(
feedback.id,
feedback.schema,
feedback.theme,
);
if (warning) console.warn(warning); // e.g. storage to connect — a person finishes that in the dashboard
console.log("synced", feedback.id, "→", formId, status);Component reference
Generated from the published subset of JSX_BLOCK_SPECS (exported by @usefillo/core) — source APIs appear here after their npm version is live. Every component also takes id (required) and visibleIf. Unknown props throw jsx-unknown_prop. The kind column is the exact string you write in a params block's kind field.
| Component | kind | Props | Children |
|---|---|---|---|
| Fillo.Text | short_text | label, description, required, placeholder, maxLength | — |
| Fillo.LongText | long_text | label, description, required, placeholder, maxLength | — |
| Fillo.Email | label, description, required, placeholder, maxLength | — | |
| Fillo.Url | url | label, description, required, placeholder, maxLength | — |
| Fillo.Phone | phone | label, description, required, placeholder, defaultCountry | — |
| Fillo.Number | number | label, description, required, placeholder, min, max, decimals, prefix, suffix, notation | — |
| Fillo.Select | select | label, description, required, placeholder, options, allowOther, shuffleOptions | <Fillo.Option> elements |
| Fillo.MultiSelect | multi_select | label, description, required, placeholder, options, allowOther, shuffleOptions | <Fillo.Option> elements |
| Fillo.Dropdown | dropdown | label, description, required, placeholder, options, allowOther, shuffleOptions | <Fillo.Option> elements |
| Fillo.Checkbox | checkbox | label, description, required, placeholder, appearance | — |
| Fillo.Rating | rating | label, description, required, placeholder, max, insightsMetric | — |
| Fillo.Scale | linear_scale | label, description, required, placeholder, min, max, minLabel, maxLabel, insightsMetric | — |
| Fillo.Ranking | ranking | label, description, required, placeholder, options | <Fillo.Option> elements |
| Fillo.Matrix | matrix | label, description, required, placeholder, rows, columns | — |
| Fillo.Signature | signature | label, description, required, placeholder | — |
| Fillo.Date | date | label, description, required, placeholder, defaultToday | — |
| Fillo.FileUpload | file_upload | label, description, required, placeholder, maxFiles, maxFileSizeMb, accept | — |
| Fillo.Hidden | hidden | label, description, required, placeholder, paramName, defaultValue | — |
| Fillo.Calculated | calculated | label, description, required, placeholder, calc, decimals, prefix, suffix | — |
| Fillo.RepeatingGroup | repeating_group | label, description, required, placeholder, minInstances, maxInstances, addLabel, itemLabel | — |
| Fillo.Custom | custom | label, description, required, placeholder, component, config | — |
| Fillo.Heading | heading | text | the text (plain string) |
| Fillo.Paragraph | paragraph | text | the text (plain string) |
| Fillo.Divider | divider | — | — |
Structural elements:
| Component | Role | Props | Children |
|---|---|---|---|
| Fillo.Page | (page) | title | the page's blocks |
| Fillo.Option | (option) | label, icon | — |
The two syntaxes compile identically
Translate between params and JSX block-by-block; ids carry over unchanged in either direction. Both compile to the same schema, so responses, logic, and piping carry over untouched whichever one you start from.
// params:
const contact = defineForm({
id: "contact",
pages: [{ id: "main", blocks: [
{ id: "email", kind: "email", label: "Work email", required: true },
]}],
});
// JSX — same id, same schema:
const contact = Fillo.defineForm(
<Fillo.Form id="contact">
<Fillo.Email id="email" label="Work email" required />
</Fillo.Form>,
);Content is identical after normalization. If the key order changes when you translate between syntaxes, the pre-normalization content hash can differ once and stage a single draft. Publish it and you're aligned; subsequent deploys are hash-stable.
What the dashboard shows
- Define in code and register the schema. For a claimed workspace, stage the schema with authenticated fillo push --stage or a server-held sync token. If the project allows publishable-key staging, the first browser render can create the same draft. A capped, unclaimed preview workspace may apply its first sync immediately in its default project.
- Publish claimed-workspace drafts in the dashboard. The draft shows up in your dashboard badged "Code managed". Publish it from the form's top bar; the browser console notice links straight there. Publishing turns on public submissions and the hosted /f page.
- Structure is read-only; operations stay yours. There is no "Edit form" on a code form — the schema ships from code on every deploy. Dashboard-owned operations survive every sync: webhooks and integrations, notification email and respondent receipts, in-progress answer visibility, resume emails and URLs, drop-off digests, file storage, and publishing.
- Later changes stay behind review. Authenticated pushes and allowed publishable-key syncs stage changed schemas beside the published form. Visitors keep the resolved live version until you re-publish, even if deployed inline code is already newer. The SDK reports that mismatch to developer diagnostics. With authenticated-only sync, a different schema must be staged first. Unchanged deploys are content-hash no-ops.
- A definition that can't render never reaches visitors. If your code ships a form definition Fillo can't render, such as the same field id twice, development shows the reason. In production the SDK shows the version published on Fillo instead, or nothing when none is published, and the browser console names the fault. The form editor and Responses show a notice explaining the fault, and the workspace owner gets at most one email a day about it.
- Responses version across deploys. Every publish snapshots a form version, and each response records the version it answered — old answers keep their meaning after fields change.
The pk_… key is publishable by design: it ships in your bundle and resolves or synchronizes code-defined forms; published form reads and responses work by form id independently. A project can require authenticated fillo push --stage or a server sync token for schema changes, or allow its public key to stage drafts; neither path lets a public key publish a live change, while capped unclaimed previews may still apply syncs immediately until claimed.
Errors
Authoring mistakes in <Fillo.Form> JSX throw FilloJsxError with a stable code; each message links to its fix at /docs/troubleshooting#jsx-<code>. This catalog is JSX-specific — writing params directly, there's no separate authoring-error layer; TypeScript's own type checking catches shape mistakes. Browse the full error catalog in the troubleshooting guide.
Related
- Schema and validation: Keep field IDs and answer shapes stable.
- Troubleshooting: Resolve JSX authoring errors.