Documentation

Welcome to the JS FormBuilder documentation. This library allows you to integrate a fully functional, drag-and-drop form builder into your web application with zero dependencies.

Zero Dependencies

This library is built with Vanilla JavaScript. It does not require React, Vue, jQuery, or any CSS framework to function.

Installation

JS FormBuilder offers two easy ways to get started. Choose the one that fits your project workflow.

Option 1: NPM (Recommended)

Best for modern web applications using bundlers like Webpack, Vite, or Rollup.

npm install @heyitsmi/form-builder

Then import it into your project:

import { FormBuilder } from '@heyitsmi/form-builder';
import '@heyitsmi/form-builder/form-builder.css';

const builder = new FormBuilder('#app');

Option 2: Browser (CDN)

Best for simple HTML pages or legacy projects. Download the form-builder.js and form-builder.css files and include them manually.

<link rel="stylesheet" href="https://unpkg.com/@heyitsmi/form-builder/form-builder.css">
<script src="https://unpkg.com/@heyitsmi/form-builder/form-builder.js"></script>

<script>
  const builder = new FormBuilder('#app');
</script>

Quick Start

To get started, create a container element in your HTML where the builder should render.

1. HTML Structure

<div id="builder-container"></div>

2. Initialize the Builder

const builder = new FormBuilder('#builder-container');

Configuration Options

You can customize the builder by passing an options object as the second argument.

const builder = new FormBuilder('#app', {
    layout: 'right',
    components: ['text', 'number']
});

Available Options

Property	Type	Description
`layout`	String	Set to `'left'` (default) or `'right'` to position the sidebar.
`components`	Array	List of components to enable. Can be strings or config objects.
`icons`	Object	Override default icons with custom SVG strings.

Layout Position

By default, the toolbox sidebar appears on the left. You can move it to the right:

layout: 'right'

Customizing Components

You can filter which components are available or rename them.

components: [
    'text',  // Use defaults
    { type: 'file', label: 'Upload CV' } // Customize label
]

Custom Icons

You can pass HTML strings (SVG or <i> tags) to replace default icons.

icons: {
    text: '<svg ...></svg>',
    number: '<i class="fa fa-hashtag"></i>'
}

API Methods

Interact with the builder instance using the following methods.

Method	Description
`getJson()`	Returns the current state of the form as an array of objects.
`on(event, callback)`	Attaches an event listener to the builder instance.

JSON Output Schema

The getJson() method returns a standardized JSON structure.

[
  {
    "id": "f_1715629102",
    "type": "text",
    "label": "Full Name",
    "required": true,
    "helperText": "Enter your legal name",
    "placeholder": "John Doe"
  }
]