markdown

Magic Form ✨

A dynamic, type-safe form builder for React with built-in validation, file uploads, and customizable styling.

(replace with actual demo image URL)

Features

• 🏗️ Dynamic form generation from configuration
• 🔒 Built-in validation with Zod
• 📁 File uploads with previews
• 🎨 Customizable styling with Tailwind CSS or regular CSS
• 🛠️ Supports all standard form inputs
• 🔄 Real-time form change callbacks
• 🖼️ Image previews for file uploads
• 🔘 Radio buttons and checkboxes support
• 👁️ Password visibility toggle
• 📱 Responsive by default

Installation

npm install suhad-magic-form
# or
yarn add suhad-magic-form

Peer Dependencies Make sure these are installed in your project:

npm install react react-dom react-hook-form zod @hookform/resolvers axios react-icons

Basic Usage

import { MagicForm } from 'suhad-magic-form';
import { z } from 'zod';

const formConfig = [
  {
    name: 'email',
    label: 'Email Address',
    type: 'email',
    placeholder: 'Enter your email',
    validation: z.string().email('Please enter a valid email'),
  },
  {
    name: 'password',
    label: 'Password',
    type: 'password',
    validation: z.string().min(8, 'Password must be at least 8 characters'),
  },
];

function App() {
  const handleSubmit = (data) => {
    console.log('Form submitted:', data);
  };

  return (
    <MagicForm
      formConfig={formConfig}
      onSubmit={handleSubmit}
    />
  );
}

Complete Example with All Features

import { MagicForm } from 'suhad-magic-form';
import { z } from 'zod';

const formConfig = [
  // Text input
  {
    name: 'username',
    label: 'Username',
    type: 'text',
    validation: z.string().min(3, 'Username too short'),
    placeholder: 'Enter your username',
  },
  
  // Email with custom styling
  {
    name: 'email',
    label: 'Email',
    type: 'email',
    validation: z.string().email('Invalid email'),
    inputStyle: 'border-2 border-blue-300 rounded-lg p-2',
  },
  
  // Password with toggle
  {
    name: 'password',
    label: 'Password',
    type: 'password',
    validation: z.string().min(8, 'Must be at least 8 characters'),
  },
  
  // Select dropdown
  {
    name: 'country',
    label: 'Country',
    type: 'select',
    options: [
      { value: 'us', label: 'United States' },
      { value: 'ca', label: 'Canada' },
    ],
    validation: z.string().min(1, 'Please select a country'),
  },
  
  // Checkbox group
  {
    name: 'interests',
    label: 'Your Interests',
    type: 'checkbox',
    options: [
      { value: 'sports', label: 'Sports' },
      { value: 'music', label: 'Music' },
    ],
  },
  
  // File upload
  {
    name: 'avatar',
    label: 'Profile Picture',
    type: 'file',
    acceptFileType: 'image',
    validationMessage: 'Please upload a profile picture',
  },
  
  // Textarea
  {
    name: 'bio',
    label: 'Biography',
    type: 'textarea',
    placeholder: 'Tell us about yourself...',
  }
];

export default function SignUpForm() {
  const handleSubmit = async (formData) => {
    console.log('Form data:', formData);
    // formData.avatar will contain the uploaded file URL
  };

  const handleFormChange = (currentValues) => {
    console.log('Form changed:', currentValues);
  };

  return (
    <div className="max-w-md mx-auto p-4">
      <h1 className="text-2xl font-bold mb-4">Sign Up</h1>
      <MagicForm
        formConfig={formConfig}
        onSubmit={handleSubmit}
        onFormChange={handleFormChange}
        btnText="Create Account"
        btnStyle="bg-blue-600 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
        defaultValues={{ country: 'us' }}
      />
    </div>
  );
}

FormField Configuration Property Type Required Description name string Yes Unique identifier for the field label string Yes Display label for the field type string Yes Input type (text, email, password, select, etc.) validation Zod schema No Validation rules using Zod options Array For select/radio/checkbox Options for select/radio/checkbox inputs placeholder string No Input placeholder text isMultiple boolean No For file inputs, allow multiple files acceptFileType string No For file inputs (image, pdf, or specific types) inputProps object No Additional HTML input attributes inputStyle string No Custom CSS classes for the input required boolean No Mark field as required validationMessage string No Custom required validation message Props Prop Type Default Description formConfig FormField[] - Array of field configurations onSubmit function - Callback when form is submitted onFormChange function - Callback when any field changes defaultValues object {} Initial form values btnText string "Submit" Submit button text formTagStyle string - CSS classes for form wrapper inputAndLabelParentStyle string - CSS classes for field container labelStyle string - CSS classes for labels inputStyle string - CSS classes for inputs (default provided) errorStyle string - CSS classes for error messages btnStyle string - CSS classes for submit button File Uploads For file uploads, the form automatically:

Shows previews of selected images

Handles the upload to Cloudinary

Returns the secure URL in the form data

{
  name: 'document',
  label: 'Upload Document',
  type: 'file',
  acceptFileType: 'pdf', // or 'image'
  isMultiple: false, // set to true for multiple files
}

Custom Cloudinary Setup To configure your own Cloudinary account:

Create a .env file in your project:

REACT_APP_CLOUDINARY_CLOUD_NAME=your_cloud_name
REACT_APP_CLOUDINARY_UPLOAD_PRESET=your_upload_preset
The form will automatically use these environment variables.

Styling Magic Form works with both Tailwind CSS and regular CSS. Example with Tailwind:

<MagicForm
  formConfig={formConfig}
  onSubmit={handleSubmit}
  formTagStyle="space-y-4"
  inputAndLabelParentStyle="mb-4"
  labelStyle="block text-gray-700 text-sm font-bold mb-1"
  inputStyle="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
  errorStyle="text-red-500 text-xs italic"
  btnStyle="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline"
/>

TypeScript Support Full TypeScript support is included. Import the types:

import { FormField, MagicFormProps } from 'suhad-magic-form';

Contributing Pull requests are welcome! For major changes, please open an issue first.

License MIT

This README provides:

• Clear installation instructions
• Multiple usage examples
• Complete documentation of all props and options
• TypeScript support information
• Styling guidance
• File upload configuration
• Contribution guidelines

You can customize the Cloudinary section, demo GIF URL, and any other specific details for your package. The structure follows best practices for NPM package documentation.