README.md

# ngx-validx 🚀

[![npm version](https://img.shields.io/npm/v/ngx-validx.svg?color=crimson)](https://www.npmjs.com/package/ngx-validx)
[![license](https://img.shields.io/npm/l/ngx-validx.svg)](https://github.com/EngYouniss/ngx-validx/blob/main/LICENSE)
[![Angular](https://img.shields.io/badge/Angular-18%2B%20%7C%2019%2B%20%7C%2020%2B-DD0031.svg)](https://angular.dev/)

A lightweight, high-performance, and automatic Angular form validation error handling library. Powered by **Angular Signals** and built natively for **Zoneless** applications, `ngx-validx` eliminates boilerplate validation code in your Reactive Forms.

---

## ✨ Features

- ⚡ **Signal-Powered Performance:** Built using modern Angular Signals for optimal change detection.
- 🎯 **Zero Boilerplate:** Automatically handles and displays validation messages with zero manual `*ngIf` checks.
- 🚀 **Zoneless Compatible:** Designed to work flawlessly in Zoneless Angular architectures.
- 🎨 **Fully Customizable:** Easily customize global error messages or override them per input control.
- 🧩 **Standalone First:** Out-of-the-box support for Standalone Components and Directives.
- 🌐 **Internationalization Ready:** Support for dynamic error message translation and global configuration.

---

## 📦 Installation

Install `ngx-validx` using `npm`:

```bash
npm install ngx-validx

---

🚀 Quick Start

1. Configure Global Validation Messages (Optional)

You can configure global validation error messages in your app.config.ts or main provider block:

import { ApplicationConfig } from '@angular/core';
import { provideValidX } from 'ngx-validx';

export const appConfig: ApplicationConfig = {
  providers: [
    provideValidX({
      showOnTouched: true,
    showOnDirty: flase,
    showOnSubmit: true,
    errorClass: 'validation-error',
    errorRole:'alert',
    animation: true,
      messages: {
        required: 'This field is required.',
        email: 'Please enter a valid email address.',
        minlength: (error) => `Minimum length is ${error.requiredLength} characters.`,
        maxlength: (error) => `Maximum length is ${error.requiredLength} characters.`,
        pattern: 'Invalid format.',
      },
      
    })
  ]
};

2. Import Directive in Component

Import the ValidX (or ngx-validx components) into your standalone component:

import { Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { ValidX } from 'ngx-validx';

@Component({
  selector: 'app-login',
  standalone: true,
  imports: [ReactiveFormsModule, ValidX],
  templateUrl: './login.component.html'
})
export class LoginComponent {
  private fb = inject(FormBuilder);

  loginForm = this.fb.group({
    email: ['', [Validators.required, Validators.email]],
    password: ['', [Validators.required, Validators.minLength(8)]]
  });

  onSubmit() {
    if (this.loginForm.valid) {
      console.log('Form Submitted:', this.loginForm.value);
    }
  }
}

3. Usage in HTML Template

Simply attach validx to your form or form controls:

<form [formGroup]="loginForm" (ngSubmit)="onSubmit()">
  
  <div class="form-group">
    <label for="email">Email</label>
    <input id="email" type="email" formControlName="email" validx />
  </div>

  <div class="form-group">
    <label for="password">Password</label>
    <input id="password" type="password" formControlName="password" validx />
  </div>

  <button type="submit">Submit</button>
</form>

---

⚙️ Advanced Configuration

Customizing Messages Per Field

You can override default/global messages for a specific input field using input parameters:

<input 
  type="text" 
  formControlName="username" 
  validx 
  [customMessages]="{
    required: 'Username cannot be blank!',
    minlength: 'Username must be at least 3 characters.'
  }" 
/>

Triggering Validation Modes

Control when validation messages appear (e.g., on touched, dirty, or submit):

<!-- Display error only after input is touched -->
<input formControlName="email" validx triggerOn="touched" />

<!-- Display error immediately on submit -->
<form [formGroup]="loginForm" validxForm>
  <input formControlName="email" validx />
</form>

---

🔧 API Reference

provideValidX(config)

Global provider function to set up configuration.

Option	Type	Description
messages	`Record<string, string	Function>`
trigger	`'touched'	'dirty'

ValidX Inputs

Property	Type	Default	Description
customMessages	Record<string, string>	undefined	Local override for validation error messages.
triggerOn	`'touched'	'dirty'	'submit'`

---

💻 Compatibility

Angular Version	Compatibility
v20.x	✅ Full Support
v19.x	✅ Full Support
v18.x	✅ Full Support
< v18.0	❌ Not Supported

---

📄 License

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

---

👨‍💻 Author

Developed and maintained with ❤️ by Younis Tallan

• Email: younistallan@gmail.com
• GitHub: @EngYouniss