ion-form-express is a powerful, flexible form generation library for Ionic Angular applications. It provides dynamic form creation with extensive input types, validation support, and modal functionality - all optimized for mobile-first experiences.

✨ Key Features

• 🔧 20+ Input Types - Text, Email, Password, Number, Select, Date, File, Location, Currency, PIN, and more
• 📊 Comprehensive Validation - Built-in validators with custom error messages
• 🚀 Modal & Inline Modes - Display forms as modals or embedded components
• 📱 Multi-step Forms - Create wizard-style forms with step navigation
• 🎨 Fully Customizable - Custom styling and component configuration
• ⚡ Lazy Loading - Dynamic component loading for optimal performance
• 🔄 Reactive Forms - Built on Angular Reactive Forms with FormBuilder
• 📍 Location Services - Integrated location input with Google Maps
• 📸 File Uploads - Image and file upload capabilities
• 🎯 TypeScript Support - Full type safety and IntelliSense

🛠 Installation

npm install ion-form-express

Peer Dependencies

Ensure you have the following peer dependencies installed:

npm install @angular/common@^20.0.0 @angular/core@^20.0.0

📖 Usage

Quick Start - Modal Mode

1. Import the Module

import { FormExpressModule } from 'ion-form-express';

@Component({
  selector: 'my-component',
  //...
  imports: [
    FormExpressModule
  ]
  //...
})
export class MyComponent { }

2. Use the Controller

import { Component, inject } from '@angular/core';
import { IonFormExpressController, IonFormExpress } from 'ion-form-express';

@Component({
  selector: 'app-example',
  template: `
    <ion-button (click)="openForm()">Open Form</ion-button>
  `
})
export class ExampleComponent {
  private formExpress = inject(IonFormExpressController);

  formDefinition: IonFormExpress = {
    id: 'user-registration',
    title: 'User Registration',
    fields: [
      {
        type: 'text',
        id: 'fullName',
        label: 'Full Name',
        placeholder: 'Enter your full name',
        required: true,
        validators: [{ name: 'minLength', value: 2 }]
      },
      {
        type: 'email',
        id: 'email',
        label: 'Email Address',
        required: true,
      },
      {
        type: 'password',
        id: 'password',
        label: 'Password',
        required: true,
        validators: [
          { name: 'minLength', value: 8, message: 'Password must be at least 8 characters long' },
          { name: 'pattern', value: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$' }
        ]
      },
      {
        type: 'select',
        id: 'country',
        label: 'Country',
        required: true,
        options: [
          { value: 'US', label: 'United States' },
          { value: 'CA', label: 'Canada' },
          { value: 'MX', label: 'Mexico' }
        ]
      },
      {
        type: 'checkbox',
        id: 'agreeToTerms',
        label: 'I agree to the Terms and Conditions',
        required: true
      }
    ]
  };

  async openForm() {
    try {
      const result = await this.formExpress.showFormModal(this.formDefinition);
      console.log('Form submitted:', result);
    } catch (error) {
      console.log('Form cancelled or error:', error);
    }
  }
}

Inline Component Mode

<ion-form-express
  [formDefinition]="formDefinition"
  [submitButtonText]="'Register Now'"
  [showProgress]="true"
  (formSubmit)="onFormSubmit($event)"
  (formChange)="onFormChange($event)">
</ion-form-express>

export class InlineFormComponent {
  formDefinition: IonFormExpress = {
    // ... your form definition
  };

  onFormSubmit(formData: Record<string, string>) {
    console.log('Form submitted:', formData);
  }

  onFormChange(event: IonFormExpressChangeEvent) {
    console.log('Form changed:', event);
  }
}

🎛 Available Input Types

| Type | Description | Special Features | |------|-------------|------------------| | text | Standard text input | Pattern validation, length limits | | email | Email input with validation | Built-in email format validation | | password | Secure password input | Show/hide toggle, strength validation | | number | Numeric input | Min/max values, decimal support | | currency | Currency amount input | Locale formatting, amount limits | | select | Dropdown selection | Single/multi-select, search | | date-button | Date picker button | Min/max dates, custom formats | | datetime | Date and time picker | Future date validation | | checkbox | Boolean toggle | Custom labels | | textarea | Multi-line text input | Row configuration | | file | File upload | File type restrictions, size limits | | location | Location picker | Google Maps integration | | dni | National ID input | Country-specific validation | | pin | PIN code input | Configurable length | | schedule | Schedule/time picker | Day-based time slots | | link | URL input | Link validation | | list-btns | Dynamic button list | Add/remove items |

📋 Multi-Step Forms

Create wizard-style forms with multiple steps:

const multiStepForm: IonFormExpress = {
  id: 'onboarding-wizard',
  title: 'User Onboarding',
  isMultiStep: true,
  steps: [
    {
      id: 'personal-info',
      description: 'Tell us about yourself',
      fields: [
        { type: 'text', id: 'firstName', label: 'First Name', required: true },
        { type: 'text', id: 'lastName', label: 'Last Name', required: true },
        { type: 'email', id: 'email', label: 'Email', required: true }
      ]
    },
    {
      id: 'preferences',
      description: 'Set your preferences',
      fields: [
        { type: 'select', id: 'language', label: 'Language', options: [...] },
        { type: 'checkbox', id: 'newsletter', label: 'Subscribe to newsletter' }
      ]
    }
  ]
};

🔧 Advanced Validation

Supported validators:

const fieldWithValidation: FormField = {
  type: 'text',
  id: 'username',
  label: 'Username',
  validators: [
    { name: 'required', message: 'Username is required' },
    { name: 'minLength', value: 3, message: 'Minimum 3 characters' },
    { name: 'maxLength', value: 20, message: 'Maximum 20 characters' },
    { name: 'pattern', value: '^[a-zA-Z0-9_]+$', message: 'Only letters, numbers, and underscores allowed' }
  ]
};

Available Validators:

• required - Field is mandatory
• minLength / maxLength - String length validation
• min / max - Numeric range validation
• email - Email format validation
• pattern - Custom regex validation
• acceptFiles - File type validation (for file inputs)
• maxSize - File size validation
• minDate / maxDate - Date range validation
• isFutureDate - Future date validation
• samePassword - Password confirmation
• amountMoreThanAllowed - Currency validation

🎨 Customization

Custom Styling

const styledForm: IonFormExpress = {
  id: 'styled-form',
  title: 'Custom Styled Form',
  fields: [
    {
      type: 'text',
      id: 'customField',
      label: 'Custom Field',
      class: 'custom-input-class',
      attr: {
        'custom-attribute': 'value'
      }
    }
  ]
};

(In your global.scss or variables.scss) You can setup this scss variables to change the form color:

• --ion-color-primary
• --ion-color-primary-tint
• --ion-form-express-input-bg-onvalue
• --ion-form-express-input-border-onhover
• --ion-form-express-input-label

Component Configuration

<ion-form-express
  [formDefinition]="formDefinition"
  [submitButtonText]="'Save Changes'"
  [nextButtonText]="'Continue'"
  [prevButtonText]="'Go Back'"
  [resetBtnText]="'Clear Form'"
  [showProgress]="true"
  [allowPrevStep]="true"
  [validateStepBeforeNext]="true"
  [cssClass]="'custom-form-class'"
  (formSubmit)="handleSubmit($event)"
  (stepChange)="handleStepChange($event)"
  (formChange)="handleFormChange($event)">
</ion-form-express>

📡 Events

| Event | Description | Payload | |-------|-------------|--------| | formSubmit | Form submission | Form data object | | formChange | Field value changes | { activeField, formValues, formControl } | | stepChange | Step navigation | { currentStep, totalSteps, stepId } | | resetAll | Form reset | void | | onListBtnAdded | Dynamic list item added | string[] |

🔗 Integration Features

Google Maps Integration

For location inputs, the library integrates with Google Maps:

{
  type: 'location',
  id: 'address',
  label: 'Select Location',
  required: true
}

You must add the api KEY in your index.html:

<head>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

</head>

File Upload Support

{
  type: 'file',
  id: 'profilePicture',
  label: 'Profile Picture',
  validators: [
    { 
      name: 'acceptFiles',
      value: [
        'image/jpeg', // JPG
        'image/png', // PNG
        'image/webp', // WEBP
      ],
    },
    { 
      name: 'maxSize', 
      value: 4000000, // 4mb
    }
  ]
}

🚀 Performance Features

• Lazy Loading: Components are loaded dynamically when needed
• Tree Shaking: Only used components are included in your bundle
• Standalone Components: Full support for Angular standalone architecture
• OnPush Strategy: Optimized change detection for better performance

🏗 Architecture

The library follows Angular best practices:

• Services: IonFormExpressController
• Components: 20+ specialized input components
• Models: Comprehensive TypeScript interfaces

Made with ❤️ by Isael Requena