Design a Form Builder

A form builder is a schema-driven UI compiler: a declarative description of fields, types, validation, and conditional logic is consumed at runtime by a renderer that mounts components, manages state, validates input, and persists drafts. This article is for senior frontend and platform engineers shipping form-heavy products — internal tools, low-code platforms, application flows, surveys — where forms grow into the hundreds of fields, span multiple steps, depend on each other, and have to stay usable on flaky networks and assistive tech. It covers the schema, runtime, validation, persistence, and accessibility layers, the trade-offs between the dominant stacks, and the patterns Typeform, Form.io, JSON Forms, and the React Hook Form + Zod ecosystem use under the hood.

Mental model

A form builder cleanly separates what (the schema) from how (the renderer):

1. Schema layer. A declarative description of fields, types, validation rules, and inter-field logic. The two dominant shapes are JSON Schema (data-portable, language-agnostic) and TypeScript-first schemas like Zod, TypeBox, or Valibot (type-inferring, JS-only).
2. Runtime layer. A component registry maps field types to UI components; a renderer walks the schema and mounts them; a state manager holds values, dirty state, and errors; a validation engine runs sync, async, and cross-field rules.
3. Persistence layer. Drafts auto-save into client-side storage (typically IndexedDB); on submit, the validated payload goes to the backend and the draft is cleared.

The architectural decisions you make at each layer compound:

The rest of this article is the reasoning behind each axis.

Designer and runtime: two halves of the same system

A “form builder” is two cooperating apps that share one contract — the schema document. The designer is an authoring app (drag-and-drop palette, canvas, field inspector, live preview) used by form authors; the runtime is the renderer end-users actually fill in. Both Form.io and JotForm ship this split commercially, and JSON Forms ships only the runtime half on the assumption you bring your own designer.

Three rules keep this split honest:

1. The same renderer powers preview and runtime. If the designer’s preview uses a different code path than the live form, authors will ship forms that look fine in preview and break in production.
2. The schema is versioned and the version travels with submissions and drafts. A form referenced by id alone drifts between authoring sessions; a form referenced by (id, version) is reproducible.
3. The schema is the contract. Anything the designer can express must be representable in the schema document, and anything the runtime can render must be present there — no implicit per-field code paths.

Why forms are non-trivial

Forms look like a thin UI problem and turn out to be a state-machine problem with strong UX, a11y, and persistence requirements layered on top. The non-obvious parts are the ones that decide whether a 200-field application form ships:

• Field visibility is a function of other fields. Conditional rendering and cascading dropdowns mean the form’s shape changes mid-edit; stale dependent values silently corrupt submissions.
• Validation rules cross field boundaries. Cross-field constraints (endDate > startDate, “venue required if in-person”) cannot live inside a single field’s validator.
• The performance budget is harsh. A 60 Hz frame is a 16.67 ms wall, and the RAIL model reserves only ~50 ms of that for input handling. A naive controlled form re-rendering 100 components per keystroke will miss it on a mid-tier mobile device.
• Users expect autosave. Losing a half-filled application is a worse failure than rejecting the submission. Production forms persist drafts behind the scenes.
• Assistive tech matters. Validation errors that are visually obvious are invisible to a screen reader without ARIA live regions, and dynamically appearing fields disrupt focus order.

Browser constraints to budget against

Scale tiers

The right architecture changes by an order of magnitude depending on form size; these are the rough bands I plan against:

Tax software, insurance applications, and enterprise workflow forms sit firmly in the “large” band and need virtualization and isolated field state to stay responsive.

Schema to mounted form: the rendering pipeline

Independent of the schema flavor, every renderer follows the same compile-then-mount pipeline. Understanding the steps is what lets you debug “why is my field blank on first paint” or “why is my conditional rule one keystroke behind”:

The renderer’s job is small but precise:

1. Parse + normalize — coerce shorthand to canonical form; apply defaults; collect required/enum/title per field.
2. Resolve $ref and inheritance — JSON Schema $ref and Zod composition both produce a flattened tree.
3. Build the internal field tree — the runtime walks this, not the original document.
4. Compile validators — once at mount, not per keystroke. AJV ships a code generator that compiles a schema to a closed-over function; Zod builds the parser tree at definition time.
5. Build the conditional dependency graph — see the conditional engine section.
6. Walk and mount — for each node, look up the component in the registry and mount with state subscription and validator wiring.

Knowing this pipeline determines where to do the work: schema-changing ops (loading a draft against a new version, hot-swapping a layout) need a re-parse; value-changing ops do not — they just need a re-render of the subscribed slices.

Schema layer: three viable shapes

Path 1 — JSON Schema + UI Schema

JSON Schema (Draft 2020-12, plus if/then/else from Draft 7) defines the data shape and constraints in a portable JSON document. A separate UI Schema (a JSON Forms / RJSF convention) supplies rendering hints — widgets, layout, field order. The renderer walks both and mounts components from a registry; AJV validates the same schema on the server.

Show 2 hidden lines3const schema: JSONSchema7 = {4  type: "object",5  required: ["email", "role"],6  properties: {7    email: { type: "string", format: "email", title: "Email Address" },8    role: { type: "string", enum: ["admin", "user", "guest"], title: "Role" },9    permissions: { type: "array", items: { type: "string" }, title: "Permissions" },10  },11}1213const uiSchema = {14  email: { "ui:autofocus": true },15  role: { "ui:widget": "radio" },16  permissions: { "ui:widget": "checkboxes" },17}

Best for

• Forms whose definition is shared across systems (server, client, mobile, validators).
• Backend-generated forms where the server owns the schema and the client only renders.
• API-driven flows where the form is materialized from an OpenAPI spec.

Trade-offs

• ✅ Schema is data — it can be stored, versioned, diffed, and shared with non-JS validators.
• ✅ AJV is one of the fastest validators on Node and the browser; the JSON Schema test suite gives you confidence the rules behave the same everywhere.
• ❌ The UI Schema adds a parallel structure to maintain.
• ❌ Conditional logic in JSON Schema is verbose: nested if/then/else/allOf quickly out-grows what a non-author can read.

In production, JSON Forms and react-jsonschema-form are the two dominant stacks; both compose a JSON Schema + UI Schema with a pluggable renderer set (Material UI, Vuetify, Vanilla, …).

Path 2 — TypeScript-first schema (Zod, TypeBox, Valibot)

Define the schema in TypeScript with Zod, TypeBox, or Valibot. Types are inferred from the schema (z.infer<typeof S>), so write-once gives you both compile-time types and runtime validation, and the same schema can run on the server via tRPC or Remix/Next route handlers.

Show 3 hidden lines4  .object({5    email: z.string().email("Invalid email format"),6    age: z.number().min(18, "Must be 18 or older"),7    role: z.enum(["admin", "user", "guest"]),8  })9  .refine((data) => data.role !== "admin" || data.age >= 21, {10    message: "Admins must be 21+",11    path: ["age"],12  })1314type User = z.infer<typeof userSchema>1516const uniqueEmailSchema = z17  .string()18  .email()19  .refine(20    async (email) => {21      const exists = await checkEmailExists(email)22      return !exists23    },24    { message: "Email already registered" },25  )

Best for

• TypeScript-heavy codebases where the type and the validator should not drift apart.
• Validation logic that is more readable as code than as nested JSON.
• React Hook Form via @hookform/resolvers/zod.

Trade-offs

• ✅ Single source of truth for types and runtime checks; z.infer removes the chance of drift.
• ✅ Async refinements, transforms, and coercion read naturally as TypeScript.
• ❌ Not portable to non-JS backends. If your Java or Go server has to validate the same payload, you either re-encode the rules or convert via a library like zod-to-json-schema.
• ❌ The schema is code, so it cannot be edited by non-developers in a database row the way JSON Schema can.

Path 3 — Form state machine (XState)

For multi-step wizards with branching, conditional skip-logic, and async submissions, model the form itself as a finite state machine with XState. Each step is a state, transitions are gated by guards, and the machine’s context accumulates form data.

Show 5 hidden lines6  errors: Record<string, string>7}89const formMachine = createMachine({10  id: "formWizard",11  initial: "step1",12  context: {13    step1Data: null,14    step2Data: null,15    errors: {},16  } as FormContext,17  states: {18    step1: {19      on: {20        NEXT: {21          target: "step2",22          guard: "isStep1Valid",23          actions: assign({ step1Data: (_, event) => event.data }),24        },25      },26    },27    step2: {28      on: {29        NEXT: { target: "submitting", guard: "isStep2Valid" },30        BACK: "step1",31      },32    },33    submitting: {34      invoke: {35        src: "submitForm",36        onDone: "success",37        onError: { target: "error", actions: "setError" },38      },39    },40    success: { type: "final" },41    error: { on: { RETRY: "submitting" } },42  },43})

Best for

• Multi-step wizards with non-linear branching (insurance quotes, KYC flows, checkouts).
• Forms with strict ordering rules (“you cannot reach review without completing step 3”).
• Audit trails — the state graph is the spec.

Trade-offs

• ✅ Impossible transitions are statically prevented by guards.
• ✅ Async work (submission, I/O) sits inside invoke blocks with explicit onDone/onError.
• ❌ Two systems to maintain — the state machine and a per-step form library.
• ❌ Overkill for single-page forms.

Decision matrix

In practice, the two patterns I see most often in 2026 codebases are JSON Schema + JSON Forms / RJSF for low-code or backend-generated forms, and React Hook Form + Zod for product-feature forms. XState is the right answer when the wizard graph itself is the product surface.

State management

Controlled vs uncontrolled

Every form-state library lives somewhere on the controlled–uncontrolled axis. The decision affects every render:

1const [value, setValue] = useState("");2<input value={value} onChange={(e) => setValue(e.target.value)} />;

• ✅ React owns the source of truth; derived values are easy.
• ❌ Every keystroke is a state update and a render. With naive composition, that render fans out to siblings.

Show 2 hidden lines3const { register, handleSubmit } = useForm();4<input {...register("email")} />;

• ✅ The DOM holds the value; React reads on demand. Re-renders only happen on subscribed state.
• ✅ Better default scaling for large forms.
• ❌ Less direct control of intermediate values; integrating fully-controlled UI components requires Controller or useController⁴.

The exact numbers below are illustrative — they depend heavily on the component tree, memoization, and React concurrent features — but the relative ordering is consistent across benchmarks I have run:

Subscription-based updates

React Hook Form and React Final Form both wrap form state in a Proxy and let components subscribe only to the slices they read. The mechanism is documented in the React Hook Form formState reference: properties like isDirty and errors are tracked when you destructure them; never-read properties never re-trigger.

Show 3 hidden lines4  control,5  subscription: { isDirty: true, isValid: true },6})78const email = useWatch({ control, name: "email" })

This is structurally similar to selectors in Zustand or GraphQL field selection: the consumer declares what it cares about, and the framework only signals when that slice changes. It is the single biggest reason React Hook Form scales better than Formik on large forms — Formik’s render-on-every-state-change default puts a controlled re-render on every keystroke unless you reach for <FastField>.

Field-level vs form-level state

Default to form-level state because it is the simplest mental model. Move to subscriptions or field-level state when profiling shows render cascades — typically past 50 fields or when you start computing values from the entire form on every keystroke.

State dimensions every form library tracks

Form state is not just { values, errors }. The libraries that scale all expose the same handful of orthogonal flags so the UI can answer “should I show the error yet?” without lying. The names are React Hook Form’s[^rhf-formstate]; Final Form, Formik, and TanStack Form expose the same concepts under different spellings:

The classic UX guideline — don’t show field errors until the user has had a chance to finish typing — is exactly “show errors only when touched or submitCount > 0”. Designing the form library around these flags is what lets the UI stay quiet while the user is still typing and become assertive after they ask for the form to be checked.

Validation architecture

Validation is not a single check on submit — it is a sequence of events spread across focus, typing, blur, submit, and the server response. The form library’s job is to decide when each kind of validator runs, when its result becomes visible, and how server-side rejections re-enter the same flow:

Validation timing

A practical default: validate onBlur, plus debounced onChange for fields that talk to a network (username uniqueness, address lookup, gift-card balance). Reserve onChange validation for fields where the user has no useful next action without it (password strength meter).

Show 5 hidden lines6  return response.json()7}, 300)89const usernameSchema = z10  .string()11  .min(3, "Username too short")12  .refine(13    async (username) => {14      const { available } = await checkUsername(username)15      return available16    },17    { message: "Username taken" },18  )

Cross-field validation

Fields that depend on other fields cannot be validated in isolation. In Zod, superRefine is the right tool because it lets you emit multiple issues with explicit paths and codes, where refine always emits a single custom issue:

Show 2 hidden lines3const passwordSchema = z4  .object({5    password: z.string().min(8),6    confirmPassword: z.string(),7  })8  .superRefine((data, ctx) => {9    if (data.password !== data.confirmPassword) {10      ctx.addIssue({11        code: z.ZodIssueCode.custom,12        message: "Passwords don't match",13        path: ["confirmPassword"],14      })15    }16  })1718const eventSchema = z19  .object({20    eventType: z.enum(["online", "in-person"]),21    venue: z.string().optional(),22    meetingUrl: z.string().url().optional(),23  })24  .superRefine((data, ctx) => {25    if (data.eventType === "in-person" && !data.venue) {26      ctx.addIssue({27        code: z.ZodIssueCode.custom,28        message: "Venue required for in-person events",29        path: ["venue"],30      })31    }32    if (data.eventType === "online" && !data.meetingUrl) {33      ctx.addIssue({34        code: z.ZodIssueCode.custom,35        message: "Meeting URL required for online events",36        path: ["meetingUrl"],37      })38    }39  })

Validation execution order — and why object refinements can vanish

Zod (and similar libraries) execute validation in declaration order: parse / coerce, then per-field validators, then refinements. Refinements only run after every field has parsed successfully — so a missing or wrong-typed required field will silently prevent your cross-field check from ever firing. This is documented in the Zod API reference and surfaces regularly in issue threads.

1z.object({2  email: z.string().email(),3  confirmEmail: z.string(),4}).refine((data) => data.email === data.confirmEmail, { message: "Emails must match" })

Validation precedence: client is suggestive, server is authoritative

Client-side validation is a UX optimization; the server is the authority. Skipping the client costs nothing but a round-trip; skipping the server costs you data integrity. Design for both:

1. Client validators run for fast feedback. They never reject a submission on their own; they only short-circuit obviously invalid input before the network call.
2. The server runs the same rules — ideally the literal same schema, via JSON Schema or zod-to-json-schema — and is the only place that decides whether a submission is accepted.
3. Server errors come back per field. The standard envelope is RFC 9457 Problem Details (which obsoletes RFC 7807) with an errors[] extension whose entries carry a JSON Pointer⁵ into the payload and a human-readable detail.

1type ProblemErrors = { errors?: Array<{ pointer: string; detail: string }> }23async function submitWithFieldErrors(4  payload: unknown,5  setError: (path: string, error: { message: string }) => void,6) {7  const res = await fetch("/submit", {8    method: "POST",9    headers: { "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },10    body: JSON.stringify(payload),11  })12  if (res.ok) return res.json()13  if (res.status === 422) {14    const body = (await res.json()) as ProblemErrors15    for (const { pointer, detail } of body.errors ?? []) {16      const path = pointer.replace(/^#?\//, "").split("/").join(".")17      setError(path, { message: detail })18    }19  }20  throw new Error(`submit failed: ${res.status}`)21}

Dynamic rendering

Conditional engine

Conditional rules (“show venue when eventType === 'in-person'”, “options for city depend on state”) are not just if (...) return null sprinkled in JSX. They are a reactive subsystem with three responsibilities — and silently violating any one of them produces data-integrity bugs that survive validation.

1. Build a dependency graph from the rules. Walk the schema once; for each predicate, record field B depends on field A. Without this, every keystroke evaluates every rule.
2. On value change, notify only the dependents. The graph turns the cost from “rules × keystrokes” into “dependents-of-this-field × keystrokes”.
3. When a field becomes hidden, reset its stored value. A “city” left over from the previously selected state passes validation (it is still a non-empty string) but breaks downstream geocoding. JSON Forms exposes this as hideRequired/removeOnHide; RJSF leaves it to the host app, which is a footgun.

A minimal predicate-evaluator is small enough to ship in two dozen lines:

1type Predicate = (values: Record<string, unknown>) => boolean2type Rule = { field: string; visible: Predicate; deps: string[] }34function buildEngine(rules: Rule[]) {5  const dependents = new Map<string, Rule[]>()6  for (const rule of rules) {7    for (const dep of rule.deps) {8      const list = dependents.get(dep) ?? []9      list.push(rule)10      dependents.set(dep, list)11    }12  }13  return function onChange(field: string, values: Record<string, unknown>) {14    const affected = dependents.get(field) ?? []15    return affected.map((rule) => ({16      field: rule.field,17      visible: rule.visible(values),18    }))19  }20}

In the JSON Schema world, the same idea is encoded with if/then/else (Draft 7+) and dependentRequired/dependentSchemas (Draft 2019-09+); the engine still has to walk the schema to discover the dependency edges. In code-first stacks (Zod + RHF), the dependency graph is implicit in useWatch calls — a fact that becomes a problem when a non-trivial form has dozens of useWatch subscribers and you cannot reason about why the form re-rendered.

Component registry pattern

Map field types to UI components so the schema can stay implementation-agnostic:

Show 8 hidden lines9type FieldRegistry = Record<string, ComponentType<FieldProps>>;1011const fieldRegistry: FieldRegistry = {12  text: TextInput,13  email: EmailInput,14  select: SelectField,15  checkbox: CheckboxField,16  date: DatePicker,17  file: FileUpload,18  address: AddressAutocomplete,19  phone: PhoneInput,20};2122function renderField(field: SchemaField) {23  const Component = fieldRegistry[field.type];24  if (!Component) {25    console.warn(`Unknown field type: ${field.type}`);26    return null;27  }28  return <Component key={field.name} {...field} />;29}

The registry is what decouples a schema ({ type: "date" }) from a specific implementation (a native <input type="date"> vs. a third-party date picker vs. a custom popover). Both JSON Forms renderer sets and Form.io’s Formio.Components registry follow this pattern.

Conditional field rendering

Show 10 hidden lines11  condition,12  children,13}: ConditionalFieldProps) {14  const value = useWatch({ name: watchField });1516  if (!condition(value)) {17    return null;18  }1920  return <>{children}</>;21}2223<SelectField name="employmentType" options={["employed", "self-employed", "unemployed"]} />2425<ConditionalField26  watchField="employmentType"27  condition={(v) => v === "employed"}28>29  <TextInput name="employerName" label="Employer Name" />30  <TextInput name="jobTitle" label="Job Title" />31</ConditionalField>3233<ConditionalField34  watchField="employmentType"35  condition={(v) => v === "self-employed"}36>37  <TextInput name="businessName" label="Business Name" />38</ConditionalField>

Cascading dependencies

Dropdowns whose options come from previous selections need both fresh data and a reset on parent change:

Show 15 hidden lines16    enabled: Boolean(country && state),17  });1819  if (!state) return null;2021  return (22    <SelectField23      name="city"24      options={cities ?? []}25      disabled={isLoading}26      placeholder={isLoading ? "Loading cities..." : "Select city"}27    />28  );29}

Nested and array fields

Array operations

Repeatable sections (multiple phone numbers, line items, beneficiaries) need stable identity across reorders and removals — RHF’s useFieldArray issues a stable id separate from the index for exactly this reason:

Show 6 hidden lines78function PhoneNumbers() {9  const { control } = useFormContext();10  const { fields, append, remove, move } = useFieldArray({11    control,12    name: "phones",13  });1415  return (16    <div>17      {fields.map((field, index) => (18        <div key={field.id}>19          <SelectField20            name={`phones.${index}.type`}21            options={["home", "work", "mobile"]}22          />23          <TextInput name={`phones.${index}.number`} />24          <button type="button" onClick={() => remove(index)}>25            Remove26          </button>27        </div>28      ))}29      <button30        type="button"31        onClick={() => append({ type: "mobile", number: "" })}32      >33        Add Phone34      </button>35    </div>36  );37}

Using array index as the React key causes incorrect field associations whenever an item is reordered or removed — values bleed into the wrong row. Use the library-provided id.

Nested validation

Deep validation falls naturally out of Zod’s compositional API:

Show 2 hidden lines3const orderSchema = z4  .object({5    customer: z.object({6      name: z.string().min(1),7      email: z.string().email(),8    }),9    items: z10      .array(11        z.object({12          productId: z.string(),13          quantity: z.number().min(1),14          options: z15            .array(16              z.object({17                name: z.string(),18                value: z.string(),19              }),20            )21            .optional(),22        }),23      )24      .min(1, "Order must have at least one item"),25  })26  .refine((order) => order.items.reduce((sum, item) => sum + item.quantity, 0) <= 100, {27    message: "Maximum 100 items per order",28    path: ["items"],29  })

Performance with large arrays

Arrays of more than ~100 items need help:

Show 10 hidden lines1112  return (13    <div>14      <input {...register(`items.${index}.name`)} />15      <input {...register(`items.${index}.quantity`)} type="number" />16      <button type="button" onClick={onRemove}>Remove</button>17    </div>18  );19});2021{fields.map((field, index) => (22  <ItemRow23    key={field.id}24    index={index}25    onRemove={() => remove(index)}26  />27))}

Persistence and draft recovery

Autosave strategy

The goal is “user never loses input”, not “every keystroke hits storage”. Debounce writes to a couple of seconds of inactivity:

Show 8 hidden lines9async function saveDraft(formId: string, data: unknown) {10  const db = await openDB(DRAFT_DB, 1, {11    upgrade(db) {12      db.createObjectStore(DRAFT_STORE)13    },14  })15  await db.put(16    DRAFT_STORE,17    {18      data,19      savedAt: Date.now(),20    },21    formId,22  )23}2425function useAutosave(formId: string, control: Control) {26  const formData = useWatch({ control })2728  const debouncedSave = useCallback(29    debounce((data: unknown) => {30      saveDraft(formId, data)31    }, 2000),32    [formId],33  )3435  useEffect(() => {36    debouncedSave(formData)37    return () => debouncedSave.cancel()38  }, [formData, debouncedSave])39}

Why IndexedDB for drafts

The actual IndexedDB quota varies by browser — Chrome lets an origin use a substantial fraction of total disk, Firefox caps each eTLD+1 group at ~10% of disk (capped at 10 GiB), and Safari historically allowed about 1 GiB per origin⁶. Use navigator.storage.estimate() at runtime to read the real numbers, and call navigator.storage.persist() when you need the browser to resist auto-eviction. For forms with file uploads or large datasets, IndexedDB is the only reasonable option.

Draft recovery

Restore drafts on page load — but stale drafts are usually worse than none, so age-check them:

Show 10 hidden lines11async function loadDraft(formId: string): Promise<DraftData | null> {12  const db = await openDB(DRAFT_DB, 1)13  const draft = await db.get(DRAFT_STORE, formId)1415  if (!draft) return null1617  const age = Date.now() - draft.savedAt18  if (age > STALE_THRESHOLD) {19    await db.delete(DRAFT_STORE, formId)20    return null21  }2223  return draft24}2526function useDraftRecovery(formId: string, reset: UseFormReset) {27  const [hasDraft, setHasDraft] = useState(false)28  const [draftAge, setDraftAge] = useState<string>("")2930  useEffect(() => {31    loadDraft(formId).then((draft) => {32      if (draft) {33        setHasDraft(true)34        setDraftAge(formatRelativeTime(draft.savedAt))35      }36    })37  }, [formId])3839  const restoreDraft = async () => {40    const draft = await loadDraft(formId)41    if (draft) {42      reset(draft.data)43      setHasDraft(false)44    }45  }4647  const discardDraft = async () => {48    const db = await openDB(DRAFT_DB, 1)49    await db.delete(DRAFT_STORE, formId)50    setHasDraft(false)51  }5253  return { hasDraft, draftAge, restoreDraft, discardDraft }54}

Clear the draft on successful submit

1async function onSubmit(data: FormData) {2  await submitToServer(data)34  const db = await openDB(DRAFT_DB, 1)5  await db.delete(DRAFT_STORE, formId)6}

Schema versioning and draft migration

Saved drafts outlive the schema they were authored against. A user starts a 50-field application on Monday, the schema gains three new required fields on Wednesday, and they return on Friday. Without a migration story, the draft either crashes the renderer or silently submits a payload the server now rejects.

The pattern that scales is the same one MongoDB documents as the Schema Versioning Pattern and that Confluent’s Schema Registry encodes as BACKWARD_TRANSITIVE compatibility⁷:

1. Tag every saved draft with the schemaVersion it was authored against.
2. Define migration functions per version step, each transforming vN → vN+1 (drop removed fields, default new required fields, coerce changed types).
3. On load, apply the migrations in order until the draft matches the current schema.
4. Tell the user when a migration changes the meaning of their input (newly required field, dropped data, recoded enum) — silent migrations corrupt audit trails.

Show 6 hidden lines7}89function migrateDraft<T>(draft: Draft<T>, currentVersion: number): Draft<T> {10  let data: any = draft.data11  for (let v = draft.schemaVersion + 1; v <= currentVersion; v++) {12    const step = migrations[v]13    if (!step) throw new Error(`No migration to v${v}`)14    data = step(data)15  }16  return { ...draft, data, schemaVersion: currentVersion }17}

The companion rule for the schema itself: prefer additive changes (new optional fields, widened enums, looser constraints) over breaking changes (renames, type changes, narrowed enums). When a breaking change is unavoidable, treat the new schema as a distinct id rather than bumping a version, so the renderer can pick a deliberately different code path for old drafts.

Submission lifecycle

A production submit handler does five things, in order:

1. Run client validators. Block on failure; focus the first invalid field.
2. Generate an idempotency key. A v4 UUID per submit attempt — the IETF Idempotency-Key draft and Stripe’s API both define this for POST and other non-idempotent methods. Without it, a network blip + user retry double-submits.
3. POST the payload with the key in the request header. Set Content-Type: application/json and Idempotency-Key: <uuid>. The same key must accompany every retry of the same logical attempt.
4. Branch on the response. 200/201 → success path: clear the draft, navigate or show the receipt. 422 with application/problem+json → map each errors[].pointer (a JSON Pointer) back to a form field path and call setError. 409 Conflict → another in-flight retry exists; back off and re-send with the same key. Network failure → exponential backoff with jitter, again with the same key. The Stripe convention is to retain the original status code and body for a bounded window (24 hours) so retries are deterministic⁸.
5. Update local state to reflect server reality. On success, transition to a “submitted” state that disables further edits; on validation failure, the form returns to “editable” with server-attached errors.

Optimistic vs pessimistic UI

For low-stakes forms (comments, edits to a single record), an optimistic UI — apply the change locally, send in the background, roll back on failure — is the right default. For high-stakes forms (payments, account creation, anything regulated), pessimistic is the right default: the user only sees the success state once the server has acknowledged it. A schema-driven form builder should expose this as a per-form flag, not a per-field one.

File uploads

File inputs are submission’s special case: the binary cannot live in application/json, and a 50 MB upload that loses its connection at 49 MB should not restart from zero. The pattern that has won in 2026 is direct-to-storage with presigned URLs: the form posts metadata to your API, the API responds with a short-lived presigned PUT URL pointing at S3 / GCS / Azure Blob, and the file bytes go straight from the browser to object storage. For files large enough to want resumable uploads, use the storage provider’s multipart upload (S3 multipart, GCS resumable) and either chunk the upload manually or wear the chunking via tus — both keep the API server out of the request data path.

Internationalization

A schema-driven form builder lives or dies by how cleanly it separates structure (in the schema) from localized strings (in i18n catalogs). Two practical patterns:

1. Store i18n keys in the schema, resolve at render time. Field title, description, and validator message slots hold translation keys; the renderer calls the host’s t() to resolve them. Zod’s error-customization API lets per-rule messages be either strings or keys; the zod-i18n-map library wires Zod into i18next, and Zod 4 ships built-in locales under zod/locales. RHF + Zod patterns commonly thread the t function into a schema factory so dynamic parts (e.g., min: 8) translate too.
2. Always carry the locale into validators. Number, date, and currency parsing must use the user’s locale via Intl.NumberFormat and Intl.DateTimeFormat rather than naive parseFloat or new Date(); Western thousand separators silently parse to NaN in many European locales.

For RTL (Arabic, Hebrew, Persian, Urdu): set dir on <html> from the active locale⁹, use CSS logical properties (margin-inline-start, padding-inline-end) instead of left/right, and verify that focus order, error icon placement, and input groups (e.g., currency-prefixed amounts) mirror correctly. Bidirectional text — an English address inside an Arabic form — needs dir="auto" or unicode-bidi: plaintext on the input itself, otherwise the cursor jumps unpredictably.

Performance optimization

Strategies for large forms

For forms with 100+ fields, three patterns do most of the work:

1. Virtualization — render only the rows on screen.

Show 5 hidden lines67function VirtualFieldList({ fields }: VirtualFieldListProps) {8  const Row = ({ index, style }: { index: number; style: React.CSSProperties }) => (9    <div style={style}>10      {renderField(fields[index])}11    </div>12  );1314  return (15    <FixedSizeList16      height={600}17      itemCount={fields.length}18      itemSize={80}19      width="100%"20    >21      {Row}22    </FixedSizeList>23  );24}

2. Section-based lazy loading — split the form into chunks the user wades through one at a time.

Show 8 hidden lines910  const sections = [11    { Component: PersonalInfoSection, title: "Personal" },12    { Component: EmploymentSection, title: "Employment" },13    { Component: FinancialSection, title: "Financial" },14  ];1516  const { Component } = sections[activeSection];1718  return (19    <Suspense fallback={<SectionSkeleton />}>20      <Component />21    </Suspense>22  );23}

3. Targeted validation — only validate the field that changed.

1const { trigger } = useFormContext();23<input4  {...register("email")}5  onBlur={() => trigger("email")}6/>;78const onSubmit = handleSubmit(async (data) => {9  const isValid = await trigger();10  if (isValid) {11    await submit(data);12  }13});

Profiling form performance

Treat form responsiveness as a first-class metric. Use the Long Tasks API to surface stalls during typing, and ship the data to your RUM:

Show 4 hidden lines5        duration: entry.duration,6        attribution: entry.attribution,7      })8    }9  }10})1112observer.observe({ entryTypes: ["longtask"] })

Targets to anchor against (the harder numbers come from Core Web Vitals¹⁰):

Accessibility

Error announcements

Use ARIA live regions to announce validation errors to assistive tech. The minimum-viable accessible error pattern is documented in WCAG technique ARIA19 and the MDN live regions guide:

Show 5 hidden lines6function ErrorMessage({ fieldId, error }: ErrorMessageProps) {7  return (8    <div9      id={`${fieldId}-error`}10      role="alert"11      aria-atomic="true"12    >13      {error && <span className="error-text">{error}</span>}14    </div>15  );16}1718function TextField({ name, label, error }: TextFieldProps) {19  return (20    <div>21      <label htmlFor={name}>{label}</label>22      <input23        id={name}24        aria-describedby={error ? `${name}-error` : undefined}25        aria-invalid={Boolean(error)}26      />27      <ErrorMessage fieldId={name} error={error} />28    </div>29  );30}

When you do want a quieter notification (e.g. a “saved” toast), use a polite live region instead of alert; polite waits for a pause in screen-reader output before announcing.

Focus management

Move focus to the first error on a failed submit so keyboard and screen-reader users do not have to hunt for it:

Show 3 hidden lines4  handleSubmit,5  setFocus,6  formState: { errors },7} = useForm()89const onSubmit = handleSubmit(10  (data) => submitToServer(data),11  (errors) => {12    const firstErrorField = Object.keys(errors)[0]13    if (firstErrorField) {14      setFocus(firstErrorField)15    }16  },17)

Dynamic field visibility

When a conditional field appears, focus often needs to land inside it for the user to know it exists:

Show 8 hidden lines9      const firstInput = containerRef.current?.querySelector("input, select, textarea");10      if (firstInput instanceof HTMLElement) {11        requestAnimationFrame(() => firstInput.focus());12      }13    }14    wasVisible.current = visible;15  }, [visible]);1617  if (!visible) return null;1819  return <div ref={containerRef}>{children}</div>;20}

Keyboard navigation

Support the patterns the platform already implies:

1<form2  onKeyDown={(e) => {3    if (4      e.key === "Enter" &&5      e.target instanceof HTMLInputElement &&6      e.target.type !== "submit"7    ) {8      e.preventDefault();9    }10  }}11>

Real-world implementations

Typeform — conversational forms

Typeform is built around the principle of a single question on screen at a time, with “Logic Jumps” that branch the conversation based on answers. The Create API is the source of truth: forms are JSON documents containing fields, logic, welcome_screens, and thankyou_screens, and any client (web, mobile, embed) renders against the same definition. The platform now also exposes “Multi-Question Pages” for the cases where the strict one-at-a-time model gets in the way.

Trade-off: focused UX, but users cannot scan the whole form to understand scope before they start.

Form.io — schema-driven enterprise builder

Form.io is a JSON-driven form platform whose drag-and-drop builder produces a JSON schema document. The same schema then powers an embedded Form Renderer SDK (vanilla JS with React, Angular, and Vue wrappers) and an auto-generated REST API for submissions. The architectural commitment is “the schema is the form”: store JSON, render anywhere, validate on the server with the same shape.

Trade-off: self-hosting cost and operational complexity in exchange for full data control and a single source of truth.

JSON Forms — framework-agnostic JSON Schema renderer

JSON Forms takes the JSON Schema + UI Schema model and exposes it as a framework-agnostic core (@jsonforms/core) with bindings for React, Angular, and Vue and a plug-in renderer-set system (Material UI, Vuetify, Vanilla). It is the closest thing in the open-source world to a “JSON Schema → form” reference implementation.

Trade-off: depends on JSON Schema and a separate UI Schema; if you want one schema for everything, you also need to teach your team the layout DSL.

React Hook Form + Zod — the modern product-feature stack

When the form lives in a TypeScript app, the dominant 2026 stack is React Hook Form + Zod (or Valibot) wired through the official Zod resolver:

1. Uncontrolled by default — minimal re-renders out of the box.
2. Type inference — the Zod schema is the type source.
3. Resolver pattern — pluggable validation; swap Zod for Yup, Joi, Valibot, or a custom resolver.
4. Small surface — RHF is ~8.6 kB gzipped¹² with zero dependencies.

Show 4 hidden lines5const schema = z.object({6  email: z.string().email(),7  password: z.string().min(8),8});910type FormData = z.infer<typeof schema>;1112function LoginForm() {13  const {14    register,15    handleSubmit,16    formState: { errors },17  } = useForm<FormData>({18    resolver: zodResolver(schema),19  });2021  return (22    <form onSubmit={handleSubmit((data) => login(data))}>23      <input {...register("email")} />24      {errors.email && <span>{errors.email.message}</span>}25    </form>26  );27}

Practical takeaways

Form-builder architecture really comes down to a small set of decisions that compound:

1. Schema format. JSON Schema for portability and cross-language servers; Zod / TypeBox / Valibot for TypeScript-first apps; XState when the wizard graph itself is the product.
2. State approach. Uncontrolled with subscriptions (React Hook Form) for performance at scale; controlled (Formik) for the simplest mental model on small forms.
3. Validation timing. onBlur as default, debounced onChange for async or network-bound fields, onSubmit for the simplest forms. The client is suggestive; the server is authoritative.
4. Submission as a lifecycle. Always send an Idempotency-Key; always handle 422 application/problem+json by mapping JSON Pointers back to fields and moving focus.
5. Designer–runtime contract. One renderer for preview and live; one versioned schema document; every saved draft tagged with the version it was authored against.

Sized by tier:

• < 50 fields. Any of the stacks works. Optimize for developer ergonomics.
• 50–200 fields. Subscription-based state, section-level lazy loading, and per-field validation triggers; profile before adding virtualization.
• > 200 fields. Virtualization is mandatory; isolate field components, memoize aggressively, and treat input latency as an SLI alongside INP.

The schema-driven move — define once, validate on client and server, render against a component registry, version the document, and migrate drafts on load — is what unlocks the holy grail of the same form definition working across web, mobile, server validation, and an internal admin UI.

Appendix

Prerequisites

• React or an equivalent component model.
• TypeScript, especially for the schema-first / type-inference paths.
• Familiarity with controlled vs uncontrolled component patterns.

Summary

• Form builders separate schema (what) from rendering (how) through component registries.
• Designer and runtime share one versioned schema document and one renderer (so preview matches live).
• The conditional engine is a build-time dependency graph + a runtime that mounts, unmounts, and resets dependent values on every relevant value change.
• Uncontrolled inputs with proxy-based subscriptions (React Hook Form) minimize re-renders for large forms.
• Zod’s superRefine enables multi-issue cross-field validation; refinements only run after per-field parses succeed.
• Client validation is fast feedback; the server is the only authority. Carry Idempotency-Key on every submit and map RFC 9457 errors[] pointers back to field paths on a 422.
• IndexedDB is the right home for drafts — localStorage caps at ~5 MiB per origin and blocks the main thread.
• Tag every draft with schemaVersion and migrate on load; prefer additive schema changes over breaking ones.
• Virtualization, section-level lazy loading, and isolated field components are the trio that scale forms past 100 fields.
• role="alert" already implies aria-live="assertive" and aria-atomic="true"; do not stack them.
• Move focus on submit error and on conditional-field reveal so keyboard and screen-reader users keep their place.
• Localize via i18n keys in the schema and Intl.* for number/date parsing; use CSS logical properties so RTL works without parallel stylesheets.

References

• JSON Schema specification (Draft 2020-12) — data shape and validation constraints.
• JSON Schema conditional validation — if / then / else semantics.
• Ajv JSON Schema validator — fastest mainstream JSON Schema validator.
• react-jsonschema-form (RJSF) — JSON Schema → React forms.
• JSON Forms — framework-agnostic JSON Schema renderer.
• React Hook Form — uncontrolled-first React form library.
• React Hook Form formState — proxy-backed subscriptions.
• React Hook Form advanced usage — performance patterns.
• Zod API — TypeScript-first schema validation.
• Zod superRefine — multi-issue cross-field validation.
• TypeBox — JSON-Schema-shaped TypeScript schemas.
• XState — state machines for complex form flows.
• Formik — controlled form library.
• React Final Form subscriptions — subscription-based state.
• MDN — ARIA live regions — dynamic-content announcements.
• W3C WCAG ARIA19 — using role=alert / live regions for errors.
• Adrian Roselli — Exposing field errors — accessible error patterns.
• Smashing — accessible form validation guide — WCAG-compliant validation patterns.
• MDN — IndexedDB API — client-side storage for drafts.
• MDN — Storage quotas and eviction — quota model and navigator.storage.
• web.dev — Storage for the web — practical quota numbers per browser.
• web.dev — RAIL model — the 16 ms / 50 ms / 100 ms budgets.
• web.dev — Interaction to Next Paint — current responsiveness Core Web Vital.
• W3C — Long Tasks API — surfacing tasks ≥ 50 ms.
• web.dev — Web workers off the main thread — moving validation off the UI thread.
• localForage — wrapper over IndexedDB.
• react-window — list virtualization.
• Typeform Developer Platform — Create API and Logic Jumps.
• Form.io open source — schema-driven enterprise builder.
• Form.io renderer guide — embedded JS SDK that consumes the schema.
• RFC 9457 — Problem Details for HTTP APIs — server error envelope; obsoletes RFC 7807.
• RFC 6901 — JSON Pointer — addressing nested fields in submissions and errors.
• IETF Idempotency-Key header draft — safe retries for POST submissions.
• Stripe — Idempotent requests — production reference implementation.
• WAI-ARIA Authoring Practices — Combobox — autocomplete, listbox, and search-in-select patterns.
• Zod — Customizing errors — per-rule messages, locales, and error maps.
• zod-i18n-map — translate Zod’s default messages with i18next.
• MongoDB — Schema Versioning Pattern — versioned documents in shared storage.
• tus — resumable uploads protocol — open protocol for resumable file uploads.