npm package: @schema-forms-data/builder
Description: Visual drag-and-drop form schema builder for SchemaForms
Author: SchemaForms
Latest version: 4.0.7

# @schema-forms-data/builder

[![npm](https://img.shields.io/npm/v/@schema-forms-data/builder)](https://www.npmjs.com/package/@schema-forms-data/builder)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)

Visual drag-and-drop form schema builder. Let your users design forms without writing JSON.

## Install

```bash
npm install @schema-forms-data/builder lucide-react
# also needs: react, react-dom, tailwindcss (for shadcn UI components)
```

## Basic usage

```tsx
import {
  BuilderProvider,
  Canvas,
  ConfigPanel,
  Palette,
} from "@schema-forms-data/builder";
import type { FormSchema } from "@schema-forms-data/core";

export default function BuilderPage() {
  const handleChange = (schema: FormSchema) => {
    console.log("Schema changed:", schema);
  };

  return (
    <BuilderProvider onSchemaChange={handleChange}>
      <div style={{ display: "flex", height: "100vh", overflow: "hidden" }}>
        {/* Left sidebar: draggable field types and preset blocks */}
        <Palette />

        {/* Center: drag-and-drop canvas */}
        <Canvas />

        {/* Right sidebar: config panel for the selected field */}
        <ConfigPanel />
      </div>
    </BuilderProvider>
  );
}
```

## Load and save a schema

```tsx
import {
  BuilderProvider,
  schemaToTree,
  treeToSchema,
} from "@schema-forms-data/builder";
import type { FormSchema } from "@schema-forms-data/core";

// Load from existing schema:
const initialState = schemaToTree(existingSchema);

<BuilderProvider
  initialConfigs={initialState.configs}
  initialContainers={initialState.containers}
  schemaId="my-schema-id"
  uploadTermsPdf={async (file, schemaId) => {
    // Upload PDF and return the upload ID
    const res = await myApi.uploadTermsPdf(file, schemaId);
    return res.uploadId;
  }}
  onSchemaChange={(schema) => {
    myApi.saveSchema(schema);
  }}
>
  {/* ... */}
</BuilderProvider>;
```

## BuilderProvider props

| Prop                | Type                                                | Description                                     |
| ------------------- | --------------------------------------------------- | ----------------------------------------------- |
| `initialConfigs`    | `Record<string, ItemConfig>`                        | Pre-load from a saved schema                    |
| `initialContainers` | `ContainersTree`                                    | Tree structure from a saved schema              |
| `initialTemplateId` | `string`                                            | Pre-select a visual template                    |
| `schemaId`          | `string`                                            | ID of the schema being edited (for PDF uploads) |
| `uploadTermsPdf`    | `(file: File, schemaId: string) => Promise<string>` | Inject PDF upload for Terms fields              |
| `onSchemaChange`    | `(schema: FormSchema) => void`                      | Called whenever the schema changes              |

## Export the schema

```tsx
import { useBuilder, treeToSchema } from "@schema-forms-data/builder";

function ExportButton() {
  const { containers, configs } = useBuilder();
  const schema = treeToSchema(containers, configs);
  return <pre>{JSON.stringify(schema, null, 2)}</pre>;
}
```

## License

MIT © [SchemaFormsData](https://github.com/SchemaFormsData)