README

A highly configurable drag & drop form building module for creating dynamic, responsive forms with an intuitive visual editor.

Demo

Table of Contents

• Features
• Installation
• Usage
• Framework Integration
• Documentation
• Development
• Contributing
• Changelog

Features

• 🎯 Drag & Drop Editing - Intuitive visual form builder
• 📐 Column/Inline Layout - Create multi-column forms and inline field groups
• 🔀 Conditional Fields - Show/hide fields based on user input
• 🎨 Custom Controls - Extensible control API for custom field types
• 🌍 i18n Support - Multi-language support out of the box
• 📱 Responsive - Mobile-friendly form editor and renderer
• ⚡ Zero Config - Works out of the box with sensible defaults
• 🔧 Highly Configurable - Extensive options and event system
• 📦 TypeScript Support - Full type definitions included
• 🎭 Preview Mode - Test forms before deployment

Installation

NPM

npm install formeo

Yarn

yarn add formeo

CDN

For quick prototyping or simple projects, you can use a CDN:

<!-- JavaScript -->
<script src="https://unpkg.com/formeo@latest/dist/formeo.umd.js"></script>

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/formeo@latest/dist/formeo.min.css">

Usage

Basic Setup

First, import Formeo into your project:

import { FormeoEditor, FormeoRenderer } from 'formeo'
import 'formeo/dist/formeo.min.css'

Creating a Form Editor

// Create a container element in your HTML
// <div id="formeo-editor"></div>

const editorOptions = {
  editorContainer: '#formeo-editor',
  // Add any additional options here
}

// Initialize the editor
const editor = new FormeoEditor(editorOptions)

Saving Form Data

// Get the form data (typically in an onSave event)
const formData = editor.formData

// Save to your backend
fetch('/api/forms', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(formData)
})

Rendering a Form

// Create a container element for the rendered form
// <div id="formeo-renderer"></div>

const rendererOptions = {
  editorContainer: '#formeo-renderer',
  // Add any additional options here
}

// Initialize the renderer and render the form
const renderer = new FormeoRenderer(rendererOptions)
renderer.render(formData)

Complete Example

import { FormeoEditor, FormeoRenderer } from 'formeo'
import 'formeo/dist/formeo.min.css'

// Set up the editor
const editor = new FormeoEditor({
  editorContainer: '#formeo-editor',
  events: {
    onSave: (formData) => {
      console.log('Form saved:', formData)
      // Render the form
      renderer.render(formData)
    }
  }
})

// Set up the renderer
const renderer = new FormeoRenderer({
  editorContainer: '#formeo-renderer'
})

TypeScript

Formeo includes TypeScript definitions. Import and use with full type support:

import { FormeoEditor, FormeoRenderer } from 'formeo'
import type { FormeoOptions, FormData } from 'formeo'

const options: FormeoOptions = {
  editorContainer: '#formeo-editor'
}

const editor = new FormeoEditor(options)
const formData: FormData = editor.formData

Framework Integration

Formeo can be integrated with popular frontend frameworks:

• React Integration Guide - Custom hooks, functional components, and Context API patterns
• Angular Integration Guide - Services, components, and standalone patterns

Documentation

Comprehensive documentation is available in the docs directory:

• Options - Complete configuration reference
• Controls - Custom field types and controls API
• Events - Available events and callbacks
• Actions - Action handlers
• Editor API - Editor methods and properties
• Build Tools - Development and build utilities

Development

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Getting Started

# Clone the repository
git clone https://github.com/Draggable/formeo.git
cd formeo

# Install dependencies
npm install

# Start development server
npm start

The demo will be available at http://localhost:5173/

Available Scripts

npm run dev          # Start development server
npm run build        # Build library and demo
npm run build:lib    # Build library only
npm test             # Run tests
npm run lint         # Lint code
npm run format       # Format code with Biome

Running Tests

# Unit tests
npm test

# End-to-end tests
npm run playwright:test

# View test report
npm run playwright:test:report

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up your development environment
• Code style and conventions
• Submitting pull requests
• Reporting issues

License

Formeo is MIT licensed.

Docs

Changelog

Made with ❤️ by Draggable