JSON-Driven Forms in React: The Complete Guide [2026]

​

What are JSON-driven forms?

{
  "form": {
    "key": "Screen",
    "type": "Screen",
    "children": [
      {
        "key": "email",
        "type": "MuiTextField",
        "props": { "label": { "value": "Email address" } },
        "schema": { "validations": [{ "key": "email" }] }
      }
    ]
  }
}

​

Why use JSON for forms instead of JSX?

​

When JSON forms are NOT the right choice

• Simple static forms — login, registration, contact — that will never change don’t benefit from JSON-driven architecture. React Hook Form or plain HTML will be simpler.
• Extremely custom UI requirements — if every field is a bespoke interactive component, the renderer will need heavy customization. Code-first is cleaner.
• Very small bundles required — JSON form renderers are larger than lightweight code-first libraries. If bundle size is a critical constraint, TanStack Form (~12 KB) or React Hook Form (~26 KB) are better choices.
• Tight TypeScript end-to-end — if you need full type inference from schema to field value, code-first approaches like TanStack Form have an architectural advantage.

​

JSON form libraries in React: 2026 comparison

• FormEngine — best when you need runtime rendering + an embeddable visual designer in one stack, and you’re using MUI or Mantine
• RJSF — best when you already have JSON Schema definitions from your backend and need a straightforward renderer; limited customization
• Uniforms — best when you want to auto-generate forms from existing Zod/JSON Schema data models; no visual authoring
• Formily — best for complex enterprise forms with reactive cross-field dependencies; steeper learning curve, strong Ant Design ecosystem
• SurveyJS — best for surveys, questionnaires, and research forms; commercial licensing required for the visual creator

​

FormEngine architecture in depth

JSON Schema
    ↓
FormViewer (runtime engine)
    ↓
View Adapter (component mapping)
    ↓
React Components (MUI / Mantine / custom)
    ↓
Rendered Form

• Form state management
• Field-level and form-level validation (Zod-backed)
• Conditional rendering (renderWhen expressions)
• Computed properties (computeType: "function")
• Event handling and action sequences
• Localization

​

The FormEngine JSON schema format

{
  "version": "1",
  "errorType": "MuiErrorWrapper",
  "tooltipType": "MuiTooltip",
  "defaultLanguage": "en-US",
  "languages": [...],
  "localization": {...},
  "form": {
    "key": "Screen",
    "type": "Screen",
    "children": [...]
  }
}

{
  "key": "fieldKey",       // unique identifier and form data key
  "type": "ComponentType", // maps to a component in the view adapter
  "props": {               // component properties (label, placeholder, etc.)
    "label": { "value": "My field" }
  },
  "schema": {              // validation rules
    "validations": [{ "key": "required" }]
  },
  "renderWhen": {          // conditional visibility
    "value": "form.data.someField === 'yes'"
  },
  "events": {              // event → action bindings
    "onClick": [
      { "name": "validate", "type": "common" }
    ]
  },
  "children": [...]        // nested components
}

​

Real-world patterns

​

Conditional fields

{
  "key": "companyName",
  "type": "MuiTextField",
  "props": { "label": { "value": "Company" } },
  "renderWhen": {
    "value": "form.data.accountType === 'business'"
  }
}

​

Computed field values

{
  "key": "summary",
  "type": "MuiTypography",
  "props": {
    "children": {
      "computeType": "function",
      "fnSource": "return `Hello, ${form.data.firstName} ${form.data.lastName}`"
    }
  }
}

​

Nested and repeatable fields

{
  "key": "addresses",
  "type": "Repeater",
  "children": [
    { "key": "street", "type": "MuiTextField", "props": { "label": { "value": "Street" } } },
    { "key": "city", "type": "MuiTextField", "props": { "label": { "value": "City" } } }
  ]
}

​

Form submission with validation

{
  "key": "submit",
  "type": "MuiButton",
  "props": { "children": { "value": "Submit" } },
  "events": {
    "onClick": [
      { "name": "validate", "type": "common", "args": { "failOnError": true } },
      { "name": "onSubmit", "type": "custom" }
    ]
  }
}

<FormViewer
  view={muiView}
  getForm={getForm}
  actions={{
    onSubmit: async (event) => {
      await fetch('/api/submit', {
        method: 'POST',
        body: JSON.stringify(event.data)
      })
    }
  }}
/>

​

Loading schema from an API

const [schema, setSchema] = useState<string | null>(null)

useEffect(() => {
  fetch(`/api/forms/${formId}`)
    .then(res => res.json())
    .then(data => setSchema(JSON.stringify(data)))
}, [formId])

const getForm = useCallback(() => schema!, [schema])

if (!schema) return <Spinner />

return <FormViewer view={muiView} getForm={getForm} />

​

Validation with JSON-driven forms

{
  "key": "age",
  "type": "MuiTextField",
  "schema": {
    "validations": [
      { "key": "required" },
      { "key": "min", "args": { "limit": 18, "message": "Must be at least 18" } },
      { "key": "max", "args": { "limit": 120 } }
    ]
  }
}

​

Performance considerations

• Parse overhead: The schema is parsed at runtime. For large schemas (hundreds of fields), consider caching the parsed schema in a useMemo and passing the stringified form via getForm.
• Bundle size: FormEngine Core adds ~245 KB gzip (or ~190 KB with MUI adapter, replacing the default components). This is larger than a code-first library. See Bundle Size Comparison for measured data.
• Re-renders: FormEngine manages its own internal state. Use useMemo and useCallback to avoid re-creating the getForm function and actions object on every render — this prevents unnecessary re-initialization of the form.

// Good: stable references
const getForm = useCallback(() => JSON.stringify(formSchema), [])
const actions = useMemo(() => ({ onSubmit: handleSubmit }), [handleSubmit])

// Bad: new function on every render, causes form re-initialization
return <FormViewer getForm={() => JSON.stringify(formSchema)} actions={{ onSubmit: handleSubmit }} />

​

Migration from code-first to JSON-first

1. Start with new forms: write any new forms as FormEngine JSON schemas
2. Identify high-change forms: forms that product teams request changes to frequently are the best migration candidates
3. Migrate validation rules: map your current Yup/Zod rules to FormEngine’s validation schema — the concepts are similar
4. Port event handlers: move onSubmit handlers to FormEngine actions — the function signatures are different but the logic is identical
5. Enable visual authoring optionally: once a form is in JSON, product managers can use FormEngine Designer to make changes without developer involvement

​

Next steps

• Dynamic form from JSON tutorial — build your first FormEngine form step-by-step
• Multi-step form tutorial — wizard with per-step validation
• Conditional fields tutorial — renderWhen patterns in practice
• Validation with Zod — use Zod schemas as custom validators
• Workflow approval forms — real-world case: multi-step approval with role-based fields
• Customer onboarding forms — plan-tiered onboarding with CRM pre-fill
• Inspection and data collection — Repeater, conditional follow-ups, signature capture
• FormEngine Core concepts — rendering, form data, actions, computed properties
• Core architecture deep dive — schema model, validation pipeline, view adapter
• Form library comparisons — FormEngine vs React Hook Form, Formik, RJSF, and more
• Bundle size benchmark — measured gzip sizes across scenarios
• FormEngine on GitHub — MIT source code and examples
• FormEngine Designer — let users build JSON forms visually; pricing