Design a Form Builder

Schema-driven form generation systems that render dynamic UIs from declarative definitions. This article covers form schema architectures, validation strategies, state management patterns, and the trade-offs that shape production form builders like Typeform, Google Forms, and enterprise low-code platforms.

Form builder architecture: schemas define structure, runtime renders and validates, persistence handles drafts and submissions.

Abstract

A form builder separates what (schema) from how (rendering) through three layers:

Schema Layer — JSON Schema or custom DSL defines field types, validation rules, and relationships. TypeScript inference provides compile-time safety.
Runtime Layer — Component registry maps field types to UI components. State manager tracks values, errors, dirty state. Validation engine supports sync, async, and cross-field rules.
Persistence Layer — Autosave to IndexedDB for draft recovery. Debounced saves prevent data loss without server overhead.

Key architectural decisions:

Decision	Options	Trade-off
State approach	Controlled vs Uncontrolled	Re-renders vs Direct DOM access
Validation timing	onChange vs onBlur vs onSubmit	Responsiveness vs Performance
Schema format	JSON Schema vs Custom DSL	Interoperability vs Flexibility
Field rendering	Eager vs Virtualized	Simplicity vs Scale

The Challenge

Why Forms Are Hard

Forms appear simple but encode complex state machines: field visibility depends on other fields, validation rules cross boundaries, and user expectations around autosave and error recovery are high.

Browser Constraints

Constraint	Impact	Mitigation
Main thread (16ms budget)	Validation blocking input	Debounce, Web Workers
Memory (mobile: 50-100MB practical)	Large form state trees	Virtualization, state pruning
localStorage (5MB)	Draft storage limits	IndexedDB (50% of disk)
Re-render cost	Sluggish typing feedback	Uncontrolled inputs, subscriptions

Scale Factors

Factor	Small	Medium	Large
Fields	< 50	50-200	> 200
Nested depth	1-2 levels	3-4 levels	5+ levels
Conditional rules	< 10	10-50	> 50
Update frequency	Submit only	Blur	Every keystroke

Large-scale forms (tax software, insurance applications, enterprise workflows) require virtualization and careful state management to remain responsive.

Design Paths

Path 1: JSON Schema + UI Schema

Architecture:

How it works:

JSON Schema defines data structure and validation constraints. A separate UI Schema specifies rendering hints (widgets, field order, layout). The renderer traverses both schemas to generate the form.


2 collapsed lines
1
// JSON Schema defines data shape and validation
2
import type { JSONSchema7 } from "json-schema"
3

4
const schema: JSONSchema7 = {
5
  type: "object",
6
  required: ["email", "role"],
7
  properties: {
8
    email: {
9
      type: "string",
10
      format: "email",
11
      title: "Email Address",
12
    },
13
    role: {
14
      type: "string",
15
      enum: ["admin", "user", "guest"],
16
      title: "Role",
17
    },
18
    permissions: {
19
      type: "array",
20
      items: { type: "string" },
21
      title: "Permissions",
22
    },
23
  },
24
}
25

26
// UI Schema controls rendering
27
const uiSchema = {
28
  email: { "ui:autofocus": true },
29
  role: { "ui:widget": "radio" },
30
  permissions: { "ui:widget": "checkboxes" },
31
}

Best for:

Standards-compliant form definitions shared across systems
Backend-generated forms (server defines schema, client renders)
API documentation integration (OpenAPI to form generation)

Device/network profile:

Works well on: Desktop, stable networks (schema fetching)
Struggles on: Low-end mobile with complex nested schemas (parsing overhead)

Implementation complexity:

Aspect	Effort
Initial setup	Low (libraries handle rendering)
Custom widgets	Medium (widget registry)
Complex conditionals	High (JSON Schema `if/then/else`)
Type safety	Medium (inference libraries exist)

Real-world example:

React JSON Schema Form (RJSF) powers forms at Mozilla, Postman, and numerous enterprise tools. The schema-first approach enables form definitions stored in databases and shared between frontend and backend validation.

Trade-offs:

✅ Schema reusable across platforms (web, mobile, validation)
✅ AJV validation is battle-tested and fast
❌ UI Schema adds second layer of complexity
❌ Complex conditional logic is verbose in JSON Schema

Path 2: TypeScript-First Schema (Zod/TypeBox)

Architecture:

How it works:

Define schemas in TypeScript with libraries like Zod or TypeBox. Types are inferred automatically—write once, get both compile-time checking and runtime validation.


3 collapsed lines
1
// TypeScript-first schema with Zod
2
import { z } from "zod"
3

4
const userSchema = z
5
  .object({
6
    email: z.string().email("Invalid email format"),
7
    age: z.number().min(18, "Must be 18 or older"),
8
    role: z.enum(["admin", "user", "guest"]),
9
    // Cross-field validation
10
  })
11
  .refine((data) => data.role !== "admin" || data.age >= 21, { message: "Admins must be 21+", path: ["age"] })
12

13
// Type is automatically inferred
14
type User = z.infer<typeof userSchema>
15
// { email: string; age: number; role: "admin" | "user" | "guest" }
16

17
// Async validation example
18
const uniqueEmailSchema = z
19
  .string()
20
  .email()
21
  .refine(
22
    async (email) => {
23
      const exists = await checkEmailExists(email)
24
      return !exists
25
    },
26
    { message: "Email already registered" },
27
  )

Best for:

TypeScript-heavy codebases wanting type inference
Complex validation logic (easier in code than JSON)
React Hook Form or similar library integration

Device/network profile:

Works well on: All devices (validation runs locally)
Struggles on: Async validation on slow networks (needs debouncing)

Implementation complexity:

Aspect	Effort
Initial setup	Low (npm install + schema)
Type inference	Automatic
Custom validation	Low (just write functions)
Schema serialization	Medium (not JSON-native)

Real-world example:

tRPC, Remix, and Next.js applications commonly use Zod for end-to-end type safety. The schema validates both client forms and server API handlers.

Trade-offs:

✅ Full TypeScript inference without code generation
✅ Complex validation logic is natural in code
✅ Excellent React Hook Form integration via resolvers
❌ Not portable to non-JS backends (unlike JSON Schema)
❌ Schema not easily stored in database

Path 3: Form State Machine (XState)

Architecture:

How it works:

Model the form as a finite state machine. Each step is a state, transitions are guarded by validation, and context holds accumulated form data. XState handles complex flows like multi-step wizards, conditional branching, and async operations.


5 collapsed lines
1
// XState form wizard machine
2
import { createMachine, assign } from "xstate"
3

4
type FormContext = {
5
  step1Data: { name: string } | null
6
  step2Data: { email: string } | null
7
  errors: Record<string, string>
8
}
9

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

Best for:

Multi-step wizards with complex branching
Forms with strict workflow requirements (can’t skip steps)
Audit trails (state machine history is explicit)

Device/network profile:

Works well on: All devices (state logic is lightweight)
Struggles on: None specific (XState is efficient)

Implementation complexity:

Aspect	Effort
Initial setup	Medium (XState learning curve)
Simple forms	Overkill
Complex flows	Low (states make flows explicit)
Debugging	Low (XState Viz, state inspection)

Real-world example:

Insurance quote flows, loan applications, and checkout processes use state machines. The explicit states prevent impossible transitions (e.g., submitting without completing required steps).

Trade-offs:

✅ Complex flows are explicit and visualizable
✅ Guards prevent invalid transitions
✅ Built-in async handling for submissions
❌ Overhead for simple single-page forms
❌ Two systems to maintain (state machine + form library)

Decision Matrix

Factor	JSON Schema	Zod/TypeBox	XState
Type safety	Medium (with inference libs)	High (native)	Medium
Portability	High (cross-platform)	Low (JS only)	Low
Complex validation	Verbose	Natural	Via guards
Multi-step flows	Manual	Manual	Built-in
Learning curve	Low	Low	Medium
Best for	API-driven forms	TS apps	Wizard flows

State Management

Controlled vs Uncontrolled

The fundamental form state decision affects every re-render:

Controlled (Formik, Redux Form):

1
// Every keystroke updates React state → re-render
2
const [value, setValue] = useState("");
3
<input value={value} onChange={(e) => setValue(e.target.value)} />;

✅ React controls the source of truth
✅ Easy to derive computed values
❌ Re-renders on every keystroke (performance cost)

Uncontrolled (React Hook Form):


2 collapsed lines
1
// DOM is source of truth, React reads on demand
2
import { useForm } from "react-hook-form";
3

4
const { register, handleSubmit } = useForm();
5
<input {...register("email")} />;
6
// Only re-renders when explicitly subscribed

✅ Minimal re-renders (DOM handles input)
✅ Better performance for large forms
❌ Less control over intermediate states
❌ Need Controller for custom components

Performance comparison (100 fields, keystroke in one field):

Approach	Re-renders	Time
Controlled (naive)	100 components	~50ms
Controlled (optimized)	1 component	~5ms
Uncontrolled	0 components	~1ms

Subscription-Based Updates

React Final Form and React Hook Form use subscriptions to limit re-renders:


3 collapsed lines
1
// Only subscribe to what you need
2
import { useFormState, useWatch } from "react-hook-form"
3

4
// Component only re-renders when these specific values change
5
const { isDirty, isValid } = useFormState({
6
  control,
7
  subscription: { isDirty: true, isValid: true },
8
})
9

10
// Watch specific field, not entire form
11
const email = useWatch({ control, name: "email" })

Design rationale: Subscriptions let components opt-in to state changes, similar to GraphQL selecting only needed fields. This prevents the cascading re-renders that plague naive form implementations.

Field-Level vs Form-Level State

Approach	State Location	Re-render Scope	Use Case
Form-level	Single store	Entire form	Simple forms
Field-level	Per-field	Single field	Large forms
Hybrid	Form + subscriptions	Subscribed only	Production apps

Recommendation: Start with form-level state (simpler). Move to subscriptions when profiling shows re-render bottlenecks (typically > 50 fields or complex computed values).

Validation Architecture

Validation Timing

Timing	UX	Performance	Use Case
onChange	Immediate feedback	High cost (every keystroke)	Critical fields
onBlur	Feedback after interaction	Low cost	Default choice
onSubmit	Batch validation	Lowest cost	Simple forms
Debounced onChange	Balanced	Medium cost	Async validation

Debounced async validation pattern:


5 collapsed lines
1
// Debounce async validation to avoid API spam
2
import { z } from "zod"
3
import debounce from "lodash.debounce"
4

5
const checkUsername = debounce(async (username: string) => {
6
  const response = await fetch(`/api/check-username?q=${username}`)
7
  return response.json()
8
}, 300)
9

10
const usernameSchema = z
11
  .string()
12
  .min(3, "Username too short")
13
  .refine(
14
    async (username) => {
15
      const { available } = await checkUsername(username)
16
      return available
17
    },
18
    { message: "Username taken" },
19
  )

Cross-Field Validation

Fields that depend on each other require schema-level validation:


2 collapsed lines
1
// Password confirmation with superRefine for control
2
import { z } from "zod"
3

4
const passwordSchema = z
5
  .object({
6
    password: z.string().min(8),
7
    confirmPassword: z.string(),
8
  })
9
  .superRefine((data, ctx) => {
10
    if (data.password !== data.confirmPassword) {
11
      ctx.addIssue({
12
        code: z.ZodIssueCode.custom,
13
        message: "Passwords don't match",
14
        path: ["confirmPassword"], // Error shows on confirm field
15
      })
16
    }
17
  })
18

19
// Conditional required field
20
const eventSchema = z
21
  .object({
22
    eventType: z.enum(["online", "in-person"]),
23
    venue: z.string().optional(),
24
    meetingUrl: z.string().url().optional(),
25
  })
26
  .superRefine((data, ctx) => {
27
    if (data.eventType === "in-person" && !data.venue) {
28
      ctx.addIssue({
29
        code: z.ZodIssueCode.custom,
30
        message: "Venue required for in-person events",
31
        path: ["venue"],
32
      })
33
    }
34
    if (data.eventType === "online" && !data.meetingUrl) {
35
      ctx.addIssue({
36
        code: z.ZodIssueCode.custom,
37
        message: "Meeting URL required for online events",
38
        path: ["meetingUrl"],
39
      })
40
    }
41
  })

Why superRefine over refine: The refine method only creates a single error with custom error code. superRefine gives full control: multiple errors, specific error codes, precise path targeting.

Validation Execution Order

Zod and similar libraries execute validation in order:

Type coercion/parsing
Built-in validators (min, max, email, etc.)
Refinements (in declaration order)

Critical limitation: Refinements on an object only run if all fields pass their individual validations first. A missing required field prevents cross-field refinements from executing.

1
// Refinement won't run if email is invalid
2
z.object({
3
  email: z.string().email(),
4
  confirmEmail: z.string(),
5
}).refine((data) => data.email === data.confirmEmail, { message: "Emails must match" })
6
// If email fails .email() check, refine never executes

Dynamic Rendering

Component Registry Pattern

Map field types to UI components for schema-driven rendering:


8 collapsed lines
1
// Component registry for dynamic field rendering
2
import type { ComponentType } from "react";
3

4
interface FieldProps {
5
  name: string;
6
  label: string;
7
  error?: string;
8
  // ... other common props
9
}
10

11
type FieldRegistry = Record<string, ComponentType<FieldProps>>;
12

13
const fieldRegistry: FieldRegistry = {
14
  text: TextInput,
15
  email: EmailInput,
16
  select: SelectField,
17
  checkbox: CheckboxField,
18
  date: DatePicker,
19
  file: FileUpload,
20
  // Custom fields
21
  address: AddressAutocomplete,
22
  phone: PhoneInput
23
};
24

25
// Renderer uses registry to instantiate components
26
function renderField(field: SchemaField) {
27
  const Component = fieldRegistry[field.type];
28
  if (!Component) {
29
    console.warn(`Unknown field type: ${field.type}`);
30
    return null;
31
  }
32
  return <Component key={field.name} {...field} />;
33
}

Why a registry: Decouples schema from implementation. The schema says “render a date field”—the registry decides whether that’s a native <input type="date">, a third-party date picker, or a custom component.

Conditional Field Rendering

Fields that show/hide based on other values:


10 collapsed lines
1
// Conditional rendering based on field values
2
import { useWatch } from "react-hook-form";
3

4
interface ConditionalFieldProps {
5
  watchField: string;
6
  condition: (value: unknown) => boolean;
7
  children: React.ReactNode;
8
}
9

10
function ConditionalField({
11
  watchField,
12
  condition,
13
  children
14
}: ConditionalFieldProps) {
15
  const value = useWatch({ name: watchField });
16

17
  if (!condition(value)) {
18
    return null;
19
  }
20

21
  return <>{children}</>;
22
}
23

24
// Usage in form
25
<SelectField name="employmentType" options={["employed", "self-employed", "unemployed"]} />
26

27
<ConditionalField
28
  watchField="employmentType"
29
  condition={(v) => v === "employed"}
30
>
31
  <TextInput name="employerName" label="Employer Name" />
32
  <TextInput name="jobTitle" label="Job Title" />
33
</ConditionalField>
34

35
<ConditionalField
36
  watchField="employmentType"
37
  condition={(v) => v === "self-employed"}
38
>
39
  <TextInput name="businessName" label="Business Name" />
40
</ConditionalField>

Cascading Dependencies

Dropdowns that depend on previous selections:


15 collapsed lines
1
// Cascading dropdowns with dependent options
2
import { useWatch, useFormContext } from "react-hook-form";
3
import { useQuery } from "@tanstack/react-query";
4

5
function CitySelect() {
6
  const { setValue } = useFormContext();
7
  const country = useWatch({ name: "country" });
8
  const state = useWatch({ name: "state" });
9

10
  // Reset downstream fields when parent changes
11
  useEffect(() => {
12
    setValue("city", "");
13
  }, [state, setValue]);
14

15
  const { data: cities, isLoading } = useQuery({
16
    queryKey: ["cities", country, state],
17
    queryFn: () => fetchCities(country, state),
18
    enabled: Boolean(country && state)
19
  });
20

21
  if (!state) return null;
22

23
  return (
24
    <SelectField
25
      name="city"
26
      options={cities ?? []}
27
      disabled={isLoading}
28
      placeholder={isLoading ? "Loading cities..." : "Select city"}
29
    />
30
  );
31
}

Design consideration: Reset dependent fields when parent changes. Stale values (city that doesn’t exist in newly selected state) cause validation errors and data integrity issues.

Nested and Array Fields

Array Field Operations

Repeatable sections (e.g., multiple phone numbers, addresses):


6 collapsed lines
1
// useFieldArray for repeatable sections
2
import { useFieldArray, useFormContext } from "react-hook-form";
3

4
interface PhoneEntry {
5
  type: "home" | "work" | "mobile";
6
  number: string;
7
}
8

9
function PhoneNumbers() {
10
  const { control } = useFormContext();
11
  const { fields, append, remove, move } = useFieldArray({
12
    control,
13
    name: "phones"
14
  });
15

16
  return (
17
    <div>
18
      {fields.map((field, index) => (
19
        <div key={field.id}> {/* Use field.id, not index */}
20
          <SelectField
21
            name={`phones.${index}.type`}
22
            options={["home", "work", "mobile"]}
23
          />
24
          <TextInput name={`phones.${index}.number`} />
25
          <button type="button" onClick={() => remove(index)}>
26
            Remove
27
          </button>
28
        </div>
29
      ))}
30
      <button
31
        type="button"
32
        onClick={() => append({ type: "mobile", number: "" })}
33
      >
34
        Add Phone
35
      </button>
36
    </div>
37
  );
38
}

Why field.id not index: React Hook Form generates stable IDs. Using array index as key causes incorrect field associations when items are reordered or removed.

Nested Validation

Deep validation for complex nested structures:


2 collapsed lines
1
// Nested array validation with Zod
2
import { z } from "zod"
3

4
const orderSchema = z
5
  .object({
6
    customer: z.object({
7
      name: z.string().min(1),
8
      email: z.string().email(),
9
    }),
10
    items: z
11
      .array(
12
        z.object({
13
          productId: z.string(),
14
          quantity: z.number().min(1),
15
          options: z
16
            .array(
17
              z.object({
18
                name: z.string(),
19
                value: z.string(),
20
              }),
21
            )
22
            .optional(),
23
        }),
24
      )
25
      .min(1, "Order must have at least one item"),
26
    // Cross-field: total validation
27
  })
28
  .refine((order) => order.items.reduce((sum, item) => sum + item.quantity, 0) <= 100, {
29
    message: "Maximum 100 items per order",
30
    path: ["items"],
31
  })

Performance with Large Arrays

Arrays with 100+ items require optimization:

Technique	Description	Impact
Virtualization	Render only visible rows	High
Memoization	`React.memo` on row component	Medium
Batch operations	`replace()` instead of multiple `append()`	Medium
Isolated state	Per-row components with own state	High


10 collapsed lines
1
// Memoized array item for performance
2
import { memo } from "react";
3
import { useFormContext } from "react-hook-form";
4

5
interface ItemRowProps {
6
  index: number;
7
  onRemove: () => void;
8
}
9

10
const ItemRow = memo(function ItemRow({ index, onRemove }: ItemRowProps) {
11
  const { register } = useFormContext();
12

13
  return (
14
    <div>
15
      <input {...register(`items.${index}.name`)} />
16
      <input {...register(`items.${index}.quantity`)} type="number" />
17
      <button type="button" onClick={onRemove}>Remove</button>
18
    </div>
19
  );
20
});
21

22
// Parent: use field.id as key, not index
23
{fields.map((field, index) => (
24
  <ItemRow
25
    key={field.id}
26
    index={index}
27
    onRemove={() => remove(index)}
28
  />
29
))}

Persistence and Draft Recovery

Autosave Strategy

Prevent data loss without overwhelming storage:


8 collapsed lines
1
// Debounced autosave to IndexedDB
2
import { useEffect, useCallback } from "react"
3
import { useWatch } from "react-hook-form"
4
import debounce from "lodash.debounce"
5
import { openDB } from "idb"
6

7
const DRAFT_DB = "form-drafts"
8
const DRAFT_STORE = "drafts"
9

10
async function saveDraft(formId: string, data: unknown) {
11
  const db = await openDB(DRAFT_DB, 1, {
12
    upgrade(db) {
13
      db.createObjectStore(DRAFT_STORE)
14
    },
15
  })
16
  await db.put(
17
    DRAFT_STORE,
18
    {
19
      data,
20
      savedAt: Date.now(),
21
    },
22
    formId,
23
  )
24
}
25

26
function useAutosave(formId: string, control: Control) {
27
  const formData = useWatch({ control })
28

29
  // Debounce saves to every 2 seconds of inactivity
30
  const debouncedSave = useCallback(
31
    debounce((data: unknown) => {
32
      saveDraft(formId, data)
33
    }, 2000),
34
    [formId],
35
  )
36

37
  useEffect(() => {
38
    debouncedSave(formData)
39
    return () => debouncedSave.cancel()
40
  }, [formData, debouncedSave])
41
}

Why IndexedDB over localStorage:

Feature	localStorage	IndexedDB
Storage limit	5MB	50% of disk
API	Synchronous (blocks)	Async
Data types	Strings only	Any (including blobs)
Structure	Key-value	Object stores with indexes

For forms with file uploads or large datasets, IndexedDB is the only viable option.

Draft Recovery

Restore drafts on page load with user confirmation:


10 collapsed lines
1
// Draft recovery with staleness check
2
import { useEffect, useState } from "react"
3
import { openDB } from "idb"
4

5
interface DraftData {
6
  data: unknown
7
  savedAt: number
8
}
9

10
const STALE_THRESHOLD = 24 * 60 * 60 * 1000 // 24 hours
11

12
async function loadDraft(formId: string): Promise<DraftData | null> {
13
  const db = await openDB(DRAFT_DB, 1)
14
  const draft = await db.get(DRAFT_STORE, formId)
15

16
  if (!draft) return null
17

18
  // Check if draft is stale
19
  const age = Date.now() - draft.savedAt
20
  if (age > STALE_THRESHOLD) {
21
    await db.delete(DRAFT_STORE, formId)
22
    return null
23
  }
24

25
  return draft
26
}
27

28
function useDraftRecovery(formId: string, reset: UseFormReset) {
29
  const [hasDraft, setHasDraft] = useState(false)
30
  const [draftAge, setDraftAge] = useState<string>("")
31

32
  useEffect(() => {
33
    loadDraft(formId).then((draft) => {
34
      if (draft) {
35
        setHasDraft(true)
36
        setDraftAge(formatRelativeTime(draft.savedAt))
37
      }
38
    })
39
  }, [formId])
40

41
  const restoreDraft = async () => {
42
    const draft = await loadDraft(formId)
43
    if (draft) {
44
      reset(draft.data)
45
      setHasDraft(false)
46
    }
47
  }
48

49
  const discardDraft = async () => {
50
    const db = await openDB(DRAFT_DB, 1)
51
    await db.delete(DRAFT_STORE, formId)
52
    setHasDraft(false)
53
  }
54

55
  return { hasDraft, draftAge, restoreDraft, discardDraft }
56
}

Clear Draft on Successful Submit

1
async function onSubmit(data: FormData) {
2
  await submitToServer(data)
3

4
  // Clear draft only after successful submission
5
  const db = await openDB(DRAFT_DB, 1)
6
  await db.delete(DRAFT_STORE, formId)
7
}

Performance Optimization

Large Form Strategies

For forms with 100+ fields:

1. Virtualization:


5 collapsed lines
1
// Virtualized form fields with react-window
2
import { FixedSizeList } from "react-window";
3

4
interface VirtualFieldListProps {
5
  fields: SchemaField[];
6
}
7

8
function VirtualFieldList({ fields }: VirtualFieldListProps) {
9
  const Row = ({ index, style }: { index: number; style: React.CSSProperties }) => (
10
    <div style={style}>
11
      {renderField(fields[index])}
12
    </div>
13
  );
14

15
  return (
16
    <FixedSizeList
17
      height={600}
18
      itemCount={fields.length}
19
      itemSize={80}
20
      width="100%"
21
    >
22
      {Row}
23
    </FixedSizeList>
24
  );
25
}

2. Section-Based Loading:


8 collapsed lines
1
// Lazy load form sections
2
import { lazy, Suspense } from "react";
3

4
const PersonalInfoSection = lazy(() => import("./sections/PersonalInfo"));
5
const EmploymentSection = lazy(() => import("./sections/Employment"));
6
const FinancialSection = lazy(() => import("./sections/Financial"));
7

8
function MultiSectionForm() {
9
  const [activeSection, setActiveSection] = useState(0);
10

11
  const sections = [
12
    { Component: PersonalInfoSection, title: "Personal" },
13
    { Component: EmploymentSection, title: "Employment" },
14
    { Component: FinancialSection, title: "Financial" }
15
  ];
16

17
  const { Component } = sections[activeSection];
18

19
  return (
20
    <Suspense fallback={<SectionSkeleton />}>
21
      <Component />
22
    </Suspense>
23
  );
24
}

3. Validation Optimization:

1
// Validate only changed fields, not entire form
2
const { trigger } = useFormContext();
3

4
// On blur, validate only this field
5
<input
6
  {...register("email")}
7
  onBlur={() => trigger("email")}
8
/>;
9

10
// On submit, validate all
11
const onSubmit = handleSubmit(async (data) => {
12
  const isValid = await trigger(); // All fields
13
  if (isValid) {
14
    await submit(data);
15
  }
16
});

Profiling Form Performance


4 collapsed lines
1
// Performance monitoring for forms
2
const observer = new PerformanceObserver((list) => {
3
  for (const entry of list.getEntries()) {
4
    if (entry.entryType === "longtask" && entry.duration > 50) {
5
      console.warn("Long task during form interaction:", {
6
        duration: entry.duration,
7
        attribution: entry.attribution,
8
      })
9
    }
10
  }
11
})
12

13
observer.observe({ entryTypes: ["longtask"] })

Performance targets:

Metric	Target	Degraded
Keystroke response	< 16ms	> 50ms
Field blur validation	< 50ms	> 200ms
Form submission	< 100ms (client)	> 500ms

Accessibility

Error Announcements

Use ARIA live regions to announce validation errors to screen readers:


5 collapsed lines
1
// Accessible error announcements
2
interface ErrorMessageProps {
3
  fieldId: string;
4
  error?: string;
5
}
6

7
function ErrorMessage({ fieldId, error }: ErrorMessageProps) {
8
  // Pre-register live region in DOM (empty)
9
  // VoiceOver on iOS requires aria-atomic
10
  return (
11
    <div
12
      id={`${fieldId}-error`}
13
      role="alert"
14
      aria-live="polite"
15
      aria-atomic="true"
16
    >
17
      {error && <span className="error-text">{error}</span>}
18
    </div>
19
  );
20
}
21

22
// Field links to error via aria-describedby
23
function TextField({ name, label, error }: TextFieldProps) {
24
  return (
25
    <div>
26
      <label htmlFor={name}>{label}</label>
27
      <input
28
        id={name}
29
        aria-describedby={error ? `${name}-error` : undefined}
30
        aria-invalid={Boolean(error)}
31
      />
32
      <ErrorMessage fieldId={name} error={error} />
33
    </div>
34
  );
35
}

Why aria-live="polite" over "assertive": Assertive interrupts screen readers immediately—use only for critical errors. Polite waits for a pause in reading, which is less disruptive for typical validation feedback.

Common mistake: Adding role="alert" AND aria-live="assertive" causes double announcements in some screen readers. role="alert" implies aria-live="assertive".

Focus Management

Move focus to first error on failed submission:


3 collapsed lines
1
// Focus first error field on submit
2
import { useForm } from "react-hook-form"
3

4
const {
5
  handleSubmit,
6
  setFocus,
7
  formState: { errors },
8
} = useForm()
9

10
const onSubmit = handleSubmit(
11
  (data) => submitToServer(data),
12
  (errors) => {
13
    // Focus first field with error
14
    const firstErrorField = Object.keys(errors)[0]
15
    if (firstErrorField) {
16
      setFocus(firstErrorField)
17
    }
18
  },
19
)

Dynamic Field Visibility

When fields appear/disappear, manage focus appropriately:


8 collapsed lines
1
// Focus management for conditional fields
2
import { useEffect, useRef } from "react";
3

4
function ConditionalField({ visible, children }: ConditionalFieldProps) {
5
  const containerRef = useRef<HTMLDivElement>(null);
6
  const wasVisible = useRef(visible);
7

8
  useEffect(() => {
9
    // Field just appeared
10
    if (visible && !wasVisible.current) {
11
      const firstInput = containerRef.current?.querySelector("input, select, textarea");
12
      if (firstInput instanceof HTMLElement) {
13
        // Delay focus to ensure DOM is ready
14
        requestAnimationFrame(() => firstInput.focus());
15
      }
16
    }
17
    wasVisible.current = visible;
18
  }, [visible]);
19

20
  if (!visible) return null;
21

22
  return <div ref={containerRef}>{children}</div>;
23
}

Support expected keyboard patterns:

Key	Action
Tab	Move to next field
Shift+Tab	Move to previous field
Enter	Submit form (if not in textarea)
Escape	Close dropdowns/modals
Arrow keys	Navigate options in select/radio

1
// Prevent accidental submit in multi-field forms
2
<form
3
  onKeyDown={(e) => {
4
    if (
5
      e.key === "Enter" &&
6
      e.target instanceof HTMLInputElement &&
7
      e.target.type !== "submit"
8
    ) {
9
      e.preventDefault();
10
    }
11
  }}
12
>

Real-World Implementations

Typeform: Conversational Forms

Architecture:

One question at a time (reduces cognitive load)
Logic jumps based on previous answers
Microservices: Create, Collect, Connect, Conclude colonies

Key insight: Typeform separates form building from response collection. The Create API enables programmatic form generation—schemas are stored centrally and rendered by lightweight clients.

Trade-off accepted: Limited field visibility (only current question) prevents users from reviewing all questions upfront.

Google Forms: Simplicity at Scale

Architecture:

12 question types covering 95% of use cases
Real-time response aggregation with charts
Tight Google Sheets integration for analysis

Key insight: Intentional simplicity. No conditional logic initially (added later). Focus on collaboration and response visualization rather than form complexity.

Trade-off accepted: Limited customization—no CSS control, minimal branding.

Form.io: Enterprise Self-Hosted

Architecture:

Drag-and-drop builder generates JSON Schema
Schema and API generated simultaneously
Multiple renderers (React, Angular, Vue, vanilla)

Key insight: The schema IS the form. Store JSON in your database, render anywhere. Backend validation uses the same schema.

Trade-off accepted: Complexity of self-hosting. Enterprise pricing for advanced features.

React Hook Form + Zod: Modern Stack

Why this combination dominates:

Uncontrolled by default — Minimal re-renders
Type inference — Schema defines types
Resolver pattern — Pluggable validation
Small bundle — ~9kb combined


4 collapsed lines
1
// The modern form stack
2
import { useForm } from "react-hook-form";
3
import { zodResolver } from "@hookform/resolvers/zod";
4
import { z } from "zod";
5

6
const schema = z.object({
7
  email: z.string().email(),
8
  password: z.string().min(8)
9
});
10

11
type FormData = z.infer<typeof schema>;
12

13
function LoginForm() {
14
  const {
15
    register,
16
    handleSubmit,
17
    formState: { errors }
18
  } = useForm<FormData>({
19
    resolver: zodResolver(schema)
20
  });
21

22
  return (
23
    <form onSubmit={handleSubmit((data) => login(data))}>
24
      <input {...register("email")} />
25
      {errors.email && <span>{errors.email.message}</span>}
26
      {/* ... */}
27
    </form>
28
  );
29
}

Conclusion

Form builder architecture centers on three decisions:

Schema format — JSON Schema for portability, Zod/TypeBox for TypeScript-first, XState for complex flows
State approach — Uncontrolled with subscriptions for performance (React Hook Form), controlled for simpler mental model (Formik)
Validation timing — onBlur as default, debounced onChange for async checks, onSubmit for simple forms

For production form builders:

< 50 fields: Any approach works. Optimize for developer experience.
50-200 fields: Subscription-based state, section lazy loading, consider virtualization.
> 200 fields: Mandatory virtualization, isolated field components, aggressive memoization.

The schema-driven approach (JSON Schema or Zod) enables the holy grail: define once, validate everywhere, render anywhere.

Appendix

Prerequisites

React or equivalent component model
TypeScript (for type-safe schema approaches)
Familiarity with controlled/uncontrolled component patterns

Summary

Form builders separate schema (what) from rendering (how) through component registries
Uncontrolled inputs with subscriptions minimize re-renders for large forms
Zod’s superRefine enables complex cross-field validation with precise error paths
IndexedDB provides robust draft storage; localStorage has 5MB limit
Virtualization is mandatory for forms exceeding 100-200 fields
ARIA live regions (aria-live="polite") announce errors without disrupting screen reader flow
Focus management on error and conditional field appearance improves accessibility

References

JSON Schema Specification — Data structure and validation constraints
React JSON Schema Form — JSON Schema to React forms
JSON Forms — Framework-agnostic JSON Schema rendering
React Hook Form — Performant form library with uncontrolled inputs
React Hook Form Advanced Usage — Performance optimization patterns
Zod Documentation — TypeScript-first schema validation
TypeBox — JSON Schema with TypeScript inference
XState — State machines for complex form flows
Formik — Controlled form library for React
React Final Form Subscriptions — Subscription-based state management
ARIA Live Regions (MDN) — Dynamic content announcements
Exposing Field Errors (Adrian Roselli) — Accessible error patterns
A Guide to Accessible Form Validation (Smashing) — WCAG-compliant validation
IndexedDB API (MDN) — Client-side storage for drafts
localForage — Simplified IndexedDB interface
react-window — List virtualization for large forms
Typeform Developer Platform — Conversational form architecture
Form.io Open Source — Enterprise form builder architecture

Read more