Package Exports

@elrayes/dynamic-form-builder
@elrayes/dynamic-form-builder/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@elrayes/dynamic-form-builder) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Dynamic Form Builder

A flexible and customizable dynamic form builder with theming support for JavaScript applications.

Features

Dynamic Form Generation: Create forms dynamically from JavaScript configuration objects
Multiple Input Types: Support for text, textarea, select, checkbox, radio, file uploads, and more
Advanced Components: Integration with Select2 and CKEditor
Validation: Built-in validation with customizable rules and error messages
Theming: Easily switch between Bootstrap 5 and Tailwind CSS themes
TypeScript Support: Full TypeScript definitions for better development experience
Modal Support: Display forms in modal dialogs
Helper Text: Add explanatory text to form fields
File Uploads: Preview images and display file information

Installation
Basic Usage
Field Types
Validation
Theming
Advanced Usage
API Reference
TypeScript Support
Requirements
License

Installation

NPM

npm install @elrayes/dynamic-form-builder

Yarn

yarn add @elrayes/dynamic-form-builder

Direct Import in Laravel with Vite

In your bootstrap.js file:

import { DynamicForm, ThemeManager } from '@elrayes/dynamic-form-builder';

// Make DynamicForm and ThemeManager available globally
window.DynamicForm = DynamicForm;
window.ThemeManager = ThemeManager;

Basic Usage

Creating a Simple Form

import { DynamicForm, ThemeManager } from '@elrayes/dynamic-form-builder';

// Define your form configuration
const formConfig = [
  {
    type: 'text',
    name: 'username',
    label: 'Username',
    required: true,
    placeholder: 'Enter your username',
    helper: 'Username must be between 3-20 characters'
  },
  {
    type: 'email',
    name: 'email',
    label: 'Email Address',
    required: true,
    placeholder: 'Enter your email'
  },
  {
    type: 'password',
    name: 'password',
    label: 'Password',
    required: true,
    placeholder: 'Enter your password'
  },
  {
    type: 'submit',
    label: 'Register'
  }
];

// Create a new form
// If mount is not set it will create a modal
const form = new DynamicForm({
  config: formConfig,
  mount: 'form-container', // ID of the element to mount the form to
  onSubmit: async (formData, form) => {
    // Handle form submission
    try {
      const response = await fetch('/api/register', {
        method: 'POST',
        body: formData
      });
      const data = await response.json();
      console.log('Success:', data);
    } catch (error) {
      console.error('Error:', error);
    }
  }
});

Using in HTML

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

<script>
  document.addEventListener('DOMContentLoaded', function() {
    const formConfig = [
      // Your form configuration here
    ];

    const form = new DynamicForm({
      config: formConfig,
      mount: 'form-container',
      onSubmit: async (formData, form) => {
        // Handle form submission
      }
    });
  });
</script>

Field Types

The Dynamic Form Builder supports the following field types:

Basic Input Types

text - Text input
email - Email input
password - Password input
number - Number input
tel - Telephone input
url - URL input
date - Date input
color - Color picker
hidden - Hidden input

Complex Input Types

textarea - Multiline text input
select - Dropdown select
select2 - Enhanced select with jQuery Select2
checkbox - Single checkbox
radio - Radio button group
file - File upload with preview
ckeditor - Rich text editor (requires CKEditor)
submit - Submit button

Example Configuration

const formConfig = [
  // Text input
  {
    type: 'text',
    name: 'name',
    label: 'Full Name',
    required: true,
    placeholder: 'Enter your full name'
  },

  // Select dropdown
  {
    type: 'select',
    name: 'country',
    label: 'Country',
    options: [
      { label: 'United States', value: 'us' },
      { label: 'Canada', value: 'ca' },
      { label: 'United Kingdom', value: 'uk' }
    ],
    required: true
  },

  // Radio buttons
  {
    type: 'radio',
    name: 'gender',
    label: 'Gender',
    options: [
      { label: 'Male', value: 'male' },
      { label: 'Female', value: 'female' },
      { label: 'Other', value: 'other' }
    ],
    required: true
  },

  // Checkbox
  {
    type: 'checkbox',
    name: 'terms',
    label: 'I agree to the terms and conditions',
    required: true
  },

  // File upload
  {
    type: 'file',
    name: 'profile_picture',
    label: 'Profile Picture',
    accept: 'image/*'
  },

  // Submit button
  {
    type: 'submit',
    label: 'Submit'
  }
];

Validation

The Dynamic Form Builder includes built-in validation for form fields:

{
  type: 'text',
  name: 'username',
  label: 'Username',
  required: true,
  validation: {
    minLength: 3,
    maxLength: 20,
    pattern: /^[a-zA-Z0-9]+$/,
    patternMsg: 'Username can only contain letters and numbers',
    custom: (value, input, field) => {
      // Custom validation logic
      if (value === 'admin') {
        return 'Username cannot be "admin"';
      }
      return true; // Return true if valid
    }
  }
}

Theming

The Dynamic Form Builder supports multiple themes:

// Use Bootstrap 5 theme (default)
const form = new DynamicForm({
  config: formConfig,
  mount: 'form-container',
  theme: 'bootstrap5',
  onSubmit: async (formData, form) => {
    // Handle form submission
  }
});

// Use Tailwind CSS theme
const form = new DynamicForm({
  config: formConfig,
  mount: 'form-container',
  theme: 'tailwind',
  onSubmit: async (formData, form) => {
    // Handle form submission
  }
});

// Register a custom theme
import { ThemeManager } from '@elrayes/dynamic-form-builder';
import MyCustomTheme from './my-custom-theme';

ThemeManager.register('custom', new MyCustomTheme());

const form = new DynamicForm({
  config: formConfig,
  mount: 'form-container',
  theme: 'custom',
  onSubmit: async (formData, form) => {
    // Handle form submission
  }
});

Advanced Usage

const form = new DynamicForm({
  config: formConfig,
  modalOptions: {
    id: 'myFormModal',
    title: 'User Registration',
    show: true,
    staticBackdrop: true
  },
  onSubmit: async (formData, form) => {
    // Handle form submission
  }
});

Helper Text

{
  type: 'password',
  name: 'password',
  label: 'Password',
  required: true,
  helper: 'Password must be at least 8 characters and include a number and special character'
}

Select2 Integration

{
  type: 'select2',
  name: 'tags',
  label: 'Tags',
  multiple: true,
  options: [
    { label: 'JavaScript', value: 'js' },
    { label: 'PHP', value: 'php' },
    { label: 'Python', value: 'py' }
  ],
  select2Options: {
    tags: true,
    placeholder: 'Select or create tags',
    allowClear: true
  }
}

CKEditor Integration

{
  type: 'ckeditor',
  name: 'content',
  label: 'Article Content',
  required: true
}

API Reference

DynamicForm

mount: when it is not sent or null, it will create a modal

new DynamicForm({
  config: FieldConfig[],
  mount?: string | HTMLElement | null, // if set to null it will create a modal
  modalOptions?: ModalOptions,
  onSubmit: (formData: FormData, form: HTMLFormElement) => Promise<any> | any,
  onInitialized?: (instance: DynamicForm, form: HTMLFormElement, inputs: Record<string, HTMLElement | HTMLElement[]>) => void,
  theme?: string | Theme,
  waitForDOMReady?: boolean // if true, waits for DOM to be fully loaded before initializing
})

Methods

getForm(): Returns the form element
getData(): Returns the form configuration
getModalInstance(): Returns the modal instance
collectFormInputs(): Returns a map of field names to input elements
destroy(): Cleans up resources

Options

waitForDOMReady: When set to true, the form will wait for the DOM to be fully loaded before initializing. This is useful when you need to ensure all DOM elements are available before the form is rendered.

ThemeManager

// Get a registered theme
ThemeManager.get(themeName: string): Theme

// Register a new theme
ThemeManager.register(themeName: string, theme: Theme): void

// Get the default theme
ThemeManager.getDefaultTheme(): Theme

// Set the default theme
ThemeManager.setDefaultTheme(themeName: string): void

TypeScript Support

The Dynamic Form Builder includes full TypeScript support:

import { DynamicForm, ThemeManager, FieldConfig, DynamicFormOptions } from '@elrayes/dynamic-form-builder';

const config: FieldConfig[] = [
  {
    type: 'text',
    name: 'username',
    label: 'Username',
    required: true
  },
  // More fields...
];

const options: DynamicFormOptions = {
  config,
  mount: document.getElementById('form-container'),
  onSubmit: async (formData, form) => {
    // Handle form submission
  }
};

const form = new DynamicForm(options);

Requirements

jQuery 3.0+ (for Select2 integration)
Bootstrap 5 (for default theme)
CKEditor (optional, for rich text editing)
Select2 (optional, for enhanced select dropdowns)

Development

Building the Package

To build the package, run:

npm run build

This will compile the TypeScript files into JavaScript in the dist directory.

Testing

To run the tests, use:

npm test

The test script performs the following checks:

Cleans the dist directory
Builds the package using TypeScript compiler
Verifies that all expected files are created in the dist directory
Checks that the compiled files contain the expected exports and class definitions

This ensures that the package can be built correctly and that the essential components are properly exported.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Ahmed Elrayes - ahmedwaill63@gmail.com

Repository

GitHub Repository

Acknowledgments

This package was created with the assistance of:

JetBrains AI Assistant - AI-powered coding assistant
Junie - AI development assistant

@elrayes/dynamic-form-builder