react-form-builder-studio

JSON-driven form definitions, a runtime renderer (FormRenderer) for React + shadcn/ui-style components, and a drag-and-drop builder (FormStudio) with an inspector for field settings. One install — UI primitives used by the renderer and studio are included in this package (you do not install @form-studio/ui separately).

Install

npm install react-form-builder-studio

yarn add react-form-builder-studio

pnpm add react-form-builder-studio

Peer dependencies

Install these in your app alongside react-form-builder-studio (versions should satisfy the ranges below):

| Package | Range | |-------------------|--------------| | react | ^18.3.0 | | react-dom | ^18.3.0 | | react-hook-form | ^7.53.0 | | zod | ^3.23.0 |

Example:

npm install react-form-builder-studio react react-dom react-hook-form zod

Styling

The UI expects Tailwind CSS and shadcn-style design tokens (e.g. background, foreground, primary, muted, border, ring). Point your Tailwind content paths at your own files and at node_modules/react-form-builder-studio/dist/**/*.js if class names from the built bundle are not picked up by your scanner. See a full setup in the demo app referenced from the repository.

Import studio layout CSS when you use FormStudio:

import "react-form-builder-studio/studio.css";

Quick start (React)

import { FormRenderer, loadFormDefinition, type FormDefinition } from "react-form-builder-studio";
import "react-form-builder-studio/studio.css"; // optional: only needed for FormStudio

const json = `{"version":"1.0.0","meta":{"id":"demo","title":"Demo"},"form":{"submitLabel":"Send","resetVisible":true,"columns":12},"fields":[]}`;
const result = loadFormDefinition(json);
if (!result.ok) throw new Error(result.error);

export function Preview({ definition }: { definition: FormDefinition }) {
  return <FormRenderer definition={definition} onSubmit={(values) => console.log(values)} />;
}

For the visual builder, render FormStudio and wire definition / onChange (see exports and types in dist/index.d.ts).

Package entry points

| Import | Purpose | |--------|---------| | react-form-builder-studio | Main API: FormRenderer, FormStudio, schemas, helpers, types | | react-form-builder-studio/studio.css | Styles for the studio shell | | react-form-builder-studio/schemas/form-definition.schema.json | JSON Schema for FormDefinition (tooling, Ajv, $schema in editors) |

API (overview)

• saveFormDefinition, loadFormDefinition, tryLoadFormDefinition — serialize / parse and validate with Zod.
• FormRenderer — render and validate a definition with react-hook-form.
• FormStudio — palette, sortable canvas, and inspector (built with @dnd-kit).

Builder UX

FormStudio follows a common pattern: component rail, canvas, and settings inspector. That model is informed by products such as Fillout. This package is not affiliated with Fillout or any commercial form vendor.

JSON Schema (FormDefinition)

For Ajv, VS Code $schema, and other non-Zod tooling:

| Artifact | Role | |----------|------| | react-form-builder-studio/schemas/form-definition.schema.json | JSON Schema Draft 07 for FormDefinition |

From ESM (Node 20+) using import attributes:

import schema from "react-form-builder-studio/schemas/form-definition.schema.json" with { type: "json" };

Older Node / bundlers may use assert { type: "json" } instead of with { type: "json" }, or read the file from node_modules/react-form-builder-studio/schemas/form-definition.schema.json.

Editor $schema hint:

{
  "$schema": "./node_modules/react-form-builder-studio/schemas/form-definition.schema.json",
  "version": "1.0.0",
  "meta": { "id": "my-form", "title": "Contact" },
  "form": { "submitLabel": "Send", "resetVisible": true, "columns": 12 },
  "fields": []
}

Notes

• Runtime validation uses Zod (formDefinitionSchema, loadFormDefinition). The JSON Schema is for interoperability; minor differences are possible (e.g. unknown keys).
• radio, select, multiselect require a non-empty options array.

Minimal form JSON

{
  "version": "1.0.0",
  "meta": { "id": "contact", "title": "Contact us" },
  "form": { "submitLabel": "Submit", "resetVisible": true, "columns": 12 },
  "fields": [
    {
      "id": "field_email",
      "name": "email",
      "label": "Email",
      "type": "email",
      "validation": { "required": true }
    }
  ]
}

License

MIT — see the license field in the package metadata on npm.