@piyushrajyadav/formease

Intelligent form handling with validation, autosave, and accessibility features.

📖 Documentation • 🚀 Demo • 📝 Changelog

Why FormEase?

FormEase automatically handles form validation, data persistence, and accessibility without configuration. Just add it to your form and it works.

import FormEase from '@piyushrajyadav/formease';

// That's it! Auto-detects validation rules and handles everything
new FormEase('#my-form');

Installation

npm install @piyushrajyadav/formease

yarn add @piyushrajyadav/formease

pnpm add @piyushrajyadav/formease

CDN

<script src="https://unpkg.com/@piyushrajyadav/formease@latest/dist/formease.umd.min.js"></script>

Quick Start

Basic Usage

import FormEase from '@piyushrajyadav/formease';

const form = new FormEase('#contact-form', {
  autosave: true,
  validation: {
    email: [{ type: 'email', message: 'Invalid email' }],
    name: [{ type: 'required', message: 'Name required' }]
  }
});

HTML

<form id="contact-form">
  <input name="name" type="text" placeholder="Your name" required>
  <input name="email" type="email" placeholder="Your email" required>
  <button type="submit">Submit</button>
</form>

Key Features

| Feature | Description | |---------|-------------| | 🎯 Smart Validation | Auto-detects input types (email, URL, phone, password, number, date) | | 💾 Auto-Save | Persist form data to localStorage with debouncing | | ♿ Accessibility | Full ARIA support, screen-reader announcements | | 🎨 Customizable | Flexible styling, error positioning, custom validators | | 📦 Zero Dependencies | Lightweight with no external dependencies | | 🔧 Framework Agnostic | Works with Vanilla JS, React, Vue, Angular | | 💪 TypeScript | Complete type definitions included |

API Reference

Constructor

new FormEase(selector: string | HTMLFormElement, options?: FormEaseOptions)

Methods

// Validate form manually
form.validate(): boolean

// Get form data
form.getData(): FormData

// Set form data
form.setData(data: Record<string, any>): void

// Reset form
form.reset(): void

// Destroy instance
form.destroy(): void

Configuration Options

interface FormEaseOptions {
  validation?: ValidationRules;
  autosave?: {
    enabled: boolean;
    interval: number;
    key: string;
  };
  accessibility?: {
    enabled: boolean;
    announceErrors: boolean;
  };
  onSubmit?: (data: FormData) => void;
  onValidationChange?: (isValid: boolean, errors: ValidationErrors) => void;
}

Validation Rules

| Rule | Description | Example | |------|-------------|---------| | required | Field must have value | { type: 'required' } | | email | Valid email format | { type: 'email' } | | url | Valid URL format | { type: 'url' } | | minLength | Minimum character length | { type: 'minLength', value: 5 } | | maxLength | Maximum character length | { type: 'maxLength', value: 100 } | | min | Minimum numeric value | { type: 'min', value: 18 } | | max | Maximum numeric value | { type: 'max', value: 65 } | | pattern | Custom regex pattern | { type: 'pattern', value: /^\d+$/ } |

Framework Integration

React

import { useEffect, useRef } from 'react';
import FormEase from '@piyushrajyadav/formease';

function ContactForm() {
  const formRef = useRef(null);

  useEffect(() => {
    const formease = new FormEase(formRef.current, {
      onSubmit: (data) => console.log('Submit:', data)
    });
    
    return () => formease.destroy();
  }, []);

  return <form ref={formRef}>{/* form fields */}</form>;
}

Vue

<template>
  <form ref="form">
    <!-- form fields -->
  </form>
</template>

<script>
import FormEase from '@piyushrajyadav/formease';

export default {
  mounted() {
    this.formease = new FormEase(this.$refs.form);
  },
  beforeUnmount() {
    this.formease?.destroy();
  }
}
</script>

Angular

import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import FormEase from '@piyushrajyadav/formease';

@Component({
  template: '<form #form><!-- form fields --></form>'
})
export class ContactComponent implements AfterViewInit {
  @ViewChild('form') formRef!: ElementRef;
  private formease!: FormEase;

  ngAfterViewInit() {
    this.formease = new FormEase(this.formRef.nativeElement);
  }

  ngOnDestroy() {
    this.formease?.destroy();
  }
}

Advanced Examples

Custom Validation

const form = new FormEase('#form', {
  validation: {
    username: [
      { type: 'required', message: 'Username is required' },
      { type: 'minLength', value: 3, message: 'At least 3 characters' },
      { 
        type: 'custom', 
        validator: (value) => !value.includes(' '),
        message: 'No spaces allowed'
      }
    ]
  }
});

Auto-save Configuration

const form = new FormEase('#form', {
  autosave: {
    enabled: true,
    interval: 2000, // Save every 2 seconds
    key: 'contact-form-data' // localStorage key
  }
});

Event Handling

const form = new FormEase('#form', {
  onSubmit: (data) => {
    // Handle form submission
    fetch('/api/contact', {
      method: 'POST',
      body: JSON.stringify(data),
      headers: { 'Content-Type': 'application/json' }
    });
  },
  onValidationChange: (isValid, errors) => {
    console.log('Form valid:', isValid);
    console.log('Errors:', errors);
  },
  onSave: (data) => {
    console.log('Data saved to localStorage:', data);
  }
});

Browser Support

| Browser | Version | |---------|---------| | Chrome | ≥ 60 | | Firefox | ≥ 55 | | Safari | ≥ 12 | | Edge | ≥ 79 |

TypeScript Support

FormEase includes complete TypeScript definitions:

import FormEase, { FormEaseOptions, ValidationRule } from '@piyushrajyadav/formease';

const options: FormEaseOptions = {
  validation: {
    email: [{ type: 'email', message: 'Invalid email address' }]
  }
};

const form = new FormEase('#form', options);

Bundle Information

• Package size: ~12KB minified + gzipped
• Unpacked size: 396KB
• Dependencies: Zero
• Tree-shakable: Yes (ES modules)

Contributing

We welcome contributions! Please see our Contributing Guide.

License

MIT © Piyush Yadav

Support

• 📝 Documentation
• 🐛 Report Issues
• 📧 Email

Made with ❤️ by Piyush Yadav

⭐ Star on GitHub • 📦 View on NPM