@react-formgen/json-schema

A headless, type-safe, customizable, and super simple React form and data view generator from JSON Schema.

@react-formgen/json-schema transforms a JSON Schema into dynamic forms and data views with built-in validation and error handling. It leverages Ajv for validation and Zustand for efficient state management.

Use cases

1. You don't want (or don't have time) to write a bunch of forms from scratch.
2. You want to share JSON Schema with your backend to have a consistent end-to-end validation experience (one schema to rule them all! 🧙‍♂️).
3. You want to generate forms dynamically (e.g., for a CMS, a form builder, a configuration tool, etc.).

Features

• Type-safe: Ensures your forms adhere to the defined schema.
• Customizable: Allows custom templates, layouts, and rendering logic.
• Headless: Integrates with any UI component library.
• Validation: Built-in validation and error handling.

Installation

Install with npm:

npm install @react-formgen/json-schema ajv ajv-formats json-schema

with Yarn

yarn add @react-formgen/json-schema ajv ajv-formats json-schema

with pnpm

pnpm install @react-formgen/json-schema ajv ajv-formats json-schema

Usage

Here’s how you can quickly create a form using a JSON Schema:

1. Setup a new React project

npm create vite@latest react-formgen-example --template react-ts

or with Yarn

yarn create vite react-formgen-example --template react-ts

or with pnpm

pnpm create vite react-formgen-example --template react-ts

2. Define a JSON Schema

Create a src/schema.json file:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User Registration",
  "type": "object",
  "required": ["firstName", "lastName"],
  "properties": {
    "firstName": { "type": "string", "title": "First Name" },
    "lastName": { "type": "string", "title": "Last Name" },
    "age": { "type": "integer", "title": "Age" }
  }
}

3. Create the form in src/App.tsx

import React from "react";
import { Form } from "@react-formgen/json-schema";
import schema from "./schema.json";

const App = () => {
  return (
    <div>
      <h1>{schema.title}</h1>
      <Form
        schema={schema}
        onSubmit={(data) => console.log("Form submitted:", data)}
        onError={(errors) => console.error("Validation errors:", errors)}
      />
    </div>
  );
};

export default App;

4. Run the application

npm dev

or with Yarn

yarn dev

or with pnpm

pnpm dev

You will now see a form generated based on the JSON Schema, with built-in validation and error handling.

Customization

You can easily customize field rendering by passing your own field components:

import React from "react";
import { Form, BaseTemplates } from "@react-formgen/json-schema";

// Example: Custom field for string inputs
const CustomStringTemplate = ({ schema, path, value, setValue }) => (
  <div>
    <label>{schema.title}</label>
    <input value={value} onChange={(e) => setValue(e.target.value)} />
  </div>
);

const App = () => {
  const schema = {
    $schema: "http://json-schema.org/draft-07/schema#",
    title: "User Registration",
    type: "object",
    required: ["firstName", "lastName"],
    properties: {
      firstName: { type: "string", title: "First Name" },
      lastName: { type: "string", title: "Last Name" },
      age: { type: "integer", title: "Age" },
    },
  };

  const handleSubmit = (data) => {
    console.log("Form submitted with data:", data);
  };

  const handleErrors = (errors) => {
    console.error("Form submission errors:", errors);
  };

  return (
    <Form
      schema={schema}
      templates={{ ...BaseTemplates, StringTemplate: CustomStringTemplate }}
      onSubmit={handleSubmit}
      onError={handleErrors}
    />

    // a read-only data view

    <Form schema={schema} readonly />
  );
};

Known Issues

1. The library does not support all JSON Schema Draft 7 features. Some features may not work as expected or may not work at all.
2. Error messages are direct outputs from the Ajv library. As such, they may not be the most user-friendly or localized. You can (and should) customize your ajv instance to provide better error messages in your custom FormRoot component.

License

This project is licensed under the MIT License. See the LICENSE file for more information.