@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:

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

with Yarn

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

with pnpm

1pnpm 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

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

or with Yarn

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

or with pnpm

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

2. Define a JSON Schema

Create a src/schema.json file:

1{
2  "$schema": "http://json-schema.org/draft-07/schema#",
3  "title": "User Registration",
4  "type": "object",
5  "required": ["firstName", "lastName"],
6  "properties": {
7    "firstName": { "type": "string", "title": "First Name" },
8    "lastName": { "type": "string", "title": "Last Name" },
9    "age": { "type": "integer", "title": "Age" }
10  }
11}

3. Create the form in src/App.tsx

1import React from "react";
2import { Form } from "@react-formgen/json-schema";
3import schema from "./schema.json";
4
5const App = () => {
6  return (
7    <div>
8      <h1>{schema.title}</h1>
9      <Form
10        schema={schema}
11        onSubmit={(data) => console.log("Form submitted:", data)}
12        onError={(errors) => console.error("Validation errors:", errors)}
13      />
14    </div>
15  );
16};
17
18export default App;

4. Run the application

1npm dev

or with Yarn

1yarn dev

or with pnpm

1pnpm 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:

1import React from "react";
2import { Form, BaseTemplates } from "@react-formgen/json-schema";
3
4// Example: Custom field for string inputs
5const CustomStringTemplate = ({ schema, path, value, setValue }) => (
6  <div>
7    <label>{schema.title}</label>
8    <input value={value} onChange={(e) => setValue(e.target.value)} />
9  </div>
10);
11
12const App = () => {
13  const schema = {
14    $schema: "http://json-schema.org/draft-07/schema#",
15    title: "User Registration",
16    type: "object",
17    required: ["firstName", "lastName"],
18    properties: {
19      firstName: { type: "string", title: "First Name" },
20      lastName: { type: "string", title: "Last Name" },
21      age: { type: "integer", title: "Age" },
22    },
23  };
24
25  const handleSubmit = (data) => {
26    console.log("Form submitted with data:", data);
27  };
28
29  const handleErrors = (errors) => {
30    console.error("Form submission errors:", errors);
31  };
32
33  return (
34    <Form
35      schema={schema}
36      templates={{ ...BaseTemplates, StringTemplate: CustomStringTemplate }}
37      onSubmit={handleSubmit}
38      onError={handleErrors}
39    />
40
41    // a read-only data view
42
43    <Form schema={schema} readonly />
44  );
45};

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.