# ngx-mat-form-errors

A lightweight Angular library that automatically displays validation errors for Angular Material forms. Stop writing repetitive error message logic!

[![npm version](https://img.shields.io/npm/v/ngx-mat-form-errors.svg)](https://www.npmjs.com/package/ngx-mat-form-errors)
[![npm downloads](https://img.shields.io/npm/dm/ngx-mat-form-errors.svg)](https://www.npmjs.com/package/ngx-mat-form-errors)
[![Live Demo](https://img.shields.io/badge/demo-codesandbox-green?style=flat-square&logo=codesandbox)](https://codesandbox.io/p/sandbox/mat-form-errors-sr5j2x)

## Live Demo

🚀 **See it in action!** 

Check out the live demo on CodeSandbox where you can experiment with the library:

[![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-000000?style=for-the-badge&logo=codesandbox)](https://codesandbox.io/p/sandbox/mat-form-errors-sr5j2x)

The demo includes:
- ✅ Email field with required & email validation
- ✅ Password field with required & minlength validation
- ✅ Real-time error messages
- ✅ Fully editable code


## Installation

```bash
npm install ngx-mat-form-errors
```

## Quick Usage

### 1. Import the module

**For standalone components:**
```typescript
import { NgxFormErrorsModule } from 'ngx-mat-form-errors';

@Component({
  // ...
  imports: [
    // ... other imports
    NgxFormErrorsModule,
    ReactiveFormsModule,
    MatFormFieldModule,
    MatInputModule
  ]
})
export class YourComponent {}
```

**For NgModules:**
```typescript
import { NgxFormErrorsModule } from 'ngx-mat-form-errors';

@NgModule({
  imports: [
    // ... other imports
    NgxFormErrorsModule,
    ReactiveFormsModule,
    MatFormFieldModule,
    MatInputModule
  ]
})
export class AppModule {}
```

### 2. Create a form

```typescript
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class YourComponent {
  form: FormGroup;

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      email: ['', [Validators.required, Validators.email]],
      password: ['', [Validators.required, Validators.minLength(8)]]
    });
  }
}
```

### 3. Add to template

```html
<form [formGroup]="form">
  <!-- Email field -->
  <mat-form-field>
    <mat-label>Email</mat-label>
    <input matInput formControlName="email">
  </mat-form-field>
  <ngx-error field="email" label="Email"></ngx-error>

  <!-- Password field -->
  <mat-form-field>
    <mat-label>Password</mat-label>
    <input matInput type="password" formControlName="password">
  </mat-form-field>
  <ngx-error field="password" label="Password"></ngx-error>
</form>
```

That's it! Errors will automatically show when fields are invalid and touched.

## Examples

### Basic Form

```html
<mat-form-field>
  <mat-label>Username</mat-label>
  <input matInput formControlName="username">
</mat-form-field>
<ngx-error field="username" label="Username"></ngx-error>
```

### Custom Label

```html
<ngx-error field="email" label="Email address"></ngx-error>
<!-- Displays: "Email address is required" instead of "Email is required" -->
```

### Nested Form Groups

```html
<div formGroupName="address">
  <mat-form-field>
    <mat-label>Street</mat-label>
    <input matInput formControlName="street">
  </mat-form-field>
  <ngx-error field="address.street" label="Street"></ngx-error>
</div>
```

## Default Error Messages

| Error | Message |
|-------|---------|
| required | `{label} is required` |
| email | `Invalid email format` |
| minlength | `{label} must be at least {requiredLength} characters` |
| maxlength | `{label} cannot exceed {requiredLength} characters` |
| pattern | `Invalid {label} format` |
| default | `Invalid {label}` |

## Custom Error Messages

Create a custom service:

```typescript
import { Injectable } from '@angular/core';
import { ErrorService } from 'ngx-mat-form-errors';

@Injectable({ providedIn: 'root' })
export class CustomErrorService extends ErrorService {
  override getErrorMessage(errors: any, label: string): string {
    if (errors['required']) return `Please enter your ${label}`;
    if (errors['email']) return 'Enter a valid email address';
    if (errors['minlength']) return `Minimum ${errors['minlength'].requiredLength} characters required`;
    return super.getErrorMessage(errors, label);
  }
}
```

Add to providers:

```typescript
providers: [
  { provide: ErrorService, useClass: CustomErrorService }
]
```

## API

### `<ngx-error>` Component

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | string | Yes | Form control name (supports nested like "address.street") |
| `label` | string | No | Display name (defaults to field name) |

## Styling

The component uses the `.ngx-error` class:

```css
.ngx-error {
  color: #f44336;
  font-size: 12px;
  margin-top: 4px;
}
```

## Requirements

- Angular 14+
- @angular/forms
- @angular/material (optional)