# ngx-forms-validator

> Lightweight and extensible form validation library for Angular applications. Includes custom validators, reusable error messages, and simple integration with reactive forms.

Latest version **1.1.4** (published 2025-04-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install ngx-forms-validator
pnpm add ngx-forms-validator
yarn add ngx-forms-validator
bun add ngx-forms-validator
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.1.4 |
| Published | 2025-04-07 |
| First published | 2023-12-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 105.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Aaron Palacios |
| Maintainers | apalaciosdev |
| Keywords | angular, ngx, forms, validation, form validation, reactive forms, angular validators, ngx-forms-validator, custom validators, form error messages, typescript, form helper, angular forms library |

## Links

- npm: https://www.npmjs.com/package/ngx-forms-validator
- Repository: https://github.com/apalaciosdev/ngx-forms-validator
- Homepage: https://ngx-forms-validator.netlify.app
- Issues: https://github.com/apalaciosdev/ngx-forms-validator/issues
- npm.io page: https://npm.io/package/ngx-forms-validator

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2.3.0

## Alternatives

- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads

## Recent versions

- 1.1.4 (latest) — 2025-04-07
- 1.0.17 (angular-16) — 2024-07-12
- 1.0.15 (angular-14) — 2024-01-03
- 1.1.3 — 2025-04-05
- 1.1.2 — 2025-04-05
- 1.1.1 — 2025-04-05
- 1.1.0 — 2025-04-05
- 1.0.18 — 2024-07-12
- 1.0.16 — 2024-01-03
- 1.0.14 — 2024-01-02
- 1.0.13 — 2024-01-02
- 1.0.12 — 2023-12-31
- 1.0.11 — 2023-12-31
- 1.0.10 — 2023-12-25
- 1.0.9 — 2023-12-25
- … 27 more at https://npm.io/package/ngx-forms-validator/versions

## README

<h1 align="center">NGX Forms Validator</h1>
<p align="center"><strong>Tiny, fast, and made for Angular Reactive Forms</strong></p>

<p align="center">
  <a href="https://www.npmjs.com/package/ngx-forms-validator">
    <img src="https://img.shields.io/npm/v/ngx-forms-validator?style=flat-square" alt="npm version">
  </a>
  <a href="https://www.npmjs.com/package/ngx-forms-validator">
    <img src="https://img.shields.io/npm/dt/ngx-forms-validator?style=flat-square" alt="downloads">
  </a>
<!--   <a href="https://github.com/apalaciosdev/ngx-forms-validator">
    <img src="https://img.shields.io/github/stars/apalaciosdev/ngx-forms-validator?style=flat-square" alt="GitHub stars">
  </a> -->
</p>

<p align="center">
  <a href="https://ngx-forms-validator.netlify.app">📘 Docs</a> ·
  <a href="https://www.npmjs.com/package/ngx-forms-validator">📦 NPM</a> ·
  <a href="https://github.com/apalaciosdev/ngx-forms-validator">⭐ GitHub</a>
</p>

---

## ✨ Features

- 🚀 Lightweight and dependency-free
- 🎯 Focused on **Reactive Forms** for Angular
- 🌍 Multilingual support (English, Spanish, Esperanto)
- 🧩 Built-in custom validators
- 💬 Customizable error messages and styling
- 📏 Configurable behaviors like `markFieldsAsDirty` and `maxLengthWarning`

---

## 📦 Installation

Installing **NGX Forms Validator** is as simple as running a single command in your Angular project:

```bash
npm i ngx-forms-validator
```

Once installed, you're ready to import the library and start validating forms — no additional setup or dependencies required.

## ✅ Angular Compatibility

Supports Angular **14 and above** — fully compatible with the latest Angular versions.

---

## 🚀 Get Started

### 1. Set default language

```ts
import { TranslateService } from 'ngx-forms-validator';

constructor(private translateService: TranslateService) {
  this.translateService.setTranslationLanguaje('en_US');
}
```

### 2. Add validation service into your form

```ts
import { FormValidatorService } from 'ngx-forms-validator';

constructor(public formValidatorService: FormValidatorService) {}

ngOnInit(): void {
  this.form = this.formBuilder.group({
    name: ['', Validators.required]
  });

  this.formValidatorService.validateForm(this.form);
}
```

### 3. HTML structure

```html
<form [formGroup]="form">
  <div>
    <input id="name" name="name" formControlName="name" />
  </div>
</form>
```

### 4. Optional configuration

```ts
this.formValidatorService.validateForm(this.form, {
  markFieldsAsDirty: true,
  showMaxLengthWarning: true
});
```

---

## 🧪 Custom Literals

Create your own i18n literals and override the defaults:

```ts
export const customLiterals = {
  required: 'This field is required',
  email: 'Please enter a valid email'
};

this.translateService.setCustomTranslations(customLiterals);
```

---

## 🌐 Default Literals

Built-in support for:

- **en_US** (English)
- **es_ES** (Spanish)
- **eo_EO** (Esperanto)

---

## 🧱 Custom Validators

Use custom ones included in the lib:

```ts
onlyNumber → key: number
hasWhiteSpaceLine → key: whiteSpaceLine
hasLeadingWhiteSpace → key: leadingWhiteSpaceLine
hasTrailingWhiteSpace → key: trailingWhiteSpaceLine
introducedValueExists → key: introducedValueNoExist
maxByte → key: maxLength
```

Or create your own easily:

```ts
export class CustomValidators {
  public static noSpecialChars(control: AbstractControl): ValidationErrors | null {
    return /[^a-zA-Z0-9]/.test(control.value) ? { noSpecialChars: true } : null;
  }
}
```

Then add its literal key to your custom translations.

---

## 🎨 Styling Guide

To use the default styling, include the stylesheet in your `angular.json`:

```json
"styles": [
  "node_modules/ngx-forms-validator/styles/styles.scss"
]
```

You can override the styles using `.ok-field`, `.error-field`, `.warning-field`, etc.

---

## 🔔 Error Message Behavior

You can fine-tune how and when messages appear using:

- `markFieldsAsDirty`
- `showMaxLengthWarning`

---

## 🤝 Contribute

Found a bug or want to contribute? Open an issue or PR!

---

## 📄 License

MIT © [apalacios.dev](https://github.com/apalaciosdev)

---
_Source: https://npm.io/package/ngx-forms-validator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._