Angular Form Validator

![commitizen]()
![PRs]()
![npm]()

Get validation messages with zero coding in less than 30 seconds (seriously)

Created by Angular developer for Angular developers with ❤️.

Table of Contents

- Why
- Demo
- Quick Start
- Validation Messages
- When Does Validation Run
- Validators
- Changelog
- License

Why

$3

To declarative validation error messages for reactive forms. Typically you'd do something like this:

``html


`html


> Actually we only install package then add the FormValidatorModule to your module

$3

Installing with npm

`
npm install @popeyelab/ngx-validator --save
`

Installing with yarn

`
yarn add @popeyelab/ngx-validator
`

$3

_app.module.ts_

`typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { ReactiveFormsModule } from '@angular/forms';

import { FormValidatorModule } from '@popeyelab/ngx-validator';

import { AppComponent } from './app.component';

@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, BrowserAnimationsModule, ReactiveFormsModule, FormValidatorModule, AppRoutingModule],
bootstrap: [AppComponent],
})
export class AppModule {}
`

$3

_app.component.ts_

`typescript
import { Component } from '@angular/core';
import { FormControl, FormGroup, Validators } from '@angular/forms';
import { equalTo } from '@popeyelab/ngx-validator';

@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss'],
})
export class AppComponent {
form = new FormGroup({
name: new FormControl('', [Validators.required]),
email: new FormControl('', [Validators.required, Validators.email]),
password: new FormControl('', [Validators.required, Validators.minLength(6)]),
confirmPassword: new FormControl('', [Validators.required, equalTo('password')]),
});
}
`

_app.component.html_

`html


> As you can see, we don't have to do anymore in html template. The Ngx Validator will know how to display the validation messages to the user interface.

Back to top

Validation Messages

The library will capture the error (error: ValidationErrors) from the from control, then show the validation messages to UI based on the default validation messages as bellow.

| Error | Message |
| ------------- | ----------------------------------------------------- |
| required | This field is required |
| email | Email is invalid |
| max | Value should be less than or equal to {{ max }}. |
| min | Value should be greater than or equal to {{ min }}. |
| maxlength | {{ requiredLength }} characters are allowed. |
| minlength | Should have at least {{ requiredLength }} characters. |
| pattern | Invalid pattern. Please review your input. |
| range | Value should be in the range of {{ range }} |
| url | URL is invalid. |
| unknown error | [This field is invalid] |

$3

We have the following options for changing the validation message:

#### Option 1: Use form validation configuration

`typescript
import { FormValidatorModule, FormValidatorConfig } from '@popeyelab/ngx-validator';

const formValidatorConfig: Partial = {
validationMessages: {
required: 'This field is required.',
email: 'Email is invalid',
max: 'Value should be less than or equal to {{ max }}.',
maxlength: '{{ requiredLength }} characters are allowed.',
min: 'Value should be greater than or equal to {{ min }}.',
minlength: 'Should have at least {{ requiredLength }} characters.',
pattern: 'Invalid pattern. Please review your input.',
range: 'Value should be in the range of {{ range }}',
url: 'URL is invalid.',
},
};

@NgModule({
imports: [
// ...
FormValidatorModule.configure(formValidatorConfig),
],
})
export class AppModule {}
`

#### Option 2: Use validationMessages input of FormControlValidatorDirective

_app.component.html_

`html


Default Angular build-in validator functions does not support passing validation messages, so you should use the wrapped validator functions from @popeyelab/ngx-validator;

_app.component.ts_

`typescript
import { Component } from '@angular/core';
import { FormControl, FormGroup, Validators } from '@angular/forms';
import { required, equalTo, email } from '@popeyelab/ngx-validator';

@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss'],
})
export class AppComponent {
form = new FormGroup({
name: new FormControl('', [required('Please enter your name')]),
email: new FormControl('', [required('Please enter your email'), email('Email is invalid')]),
password: new FormControl('', [Validators.required, Validators.minLength(6)]),
confirmPassword: new FormControl('', [Validators.required, equalTo('password', 'Confirm password does not match')]),
});
}
`

$3

If you have a custom validator, that returns an error like the example bellow

`typescript
function color(color: string): ValidatorFn {
return (control: AbstractControl): ValidationErrors | null => {
return control.value?.toLowerCase() === color ? null : { wrongColor: { requiredColor: color, actual: control.value } };
};
}

//...
const control = new FormControl('green', color('blue'));
`

You can also add the validation message for custom form validator by

#### Option 1: Use form validation configuration

`typescript
import { FormValidatorConfig } from '@popeyelab/ngx-validator';

const formValidatorConfig: Partial = {
validationMessages: {
// ...
wrongColor: 'Invalid color',
},
};
`

#### Option 2: Use validationMessages input of FormControlValidatorDirective

_app.component.html_

`html


`typescript
function color(color: string): ValidatorFn {
return (control: AbstractControl): ValidationErrors | null => {
return control.value?.toLowerCase() === color
? null
: {
wrongColor: {
requiredColor: color,
actual: control.value,
message: 'Invalid color',
},
};
};
}
`

Back to top

When Does Validation Run

By default, ngx-validator will run validation method when:

#### Form control dirty & touched

> A controls is dirty if users have changed the value of the control on UI.
>
> A controls is touched if users have focused on the control and then focused on something else.
> For example by clicking into the control and then pressing tab or clicking on another control in the form.

#### OR Whenever users attempt to submit a form.

You can control when ngx-validator runs validation by changing the configuration depending on your needs.

`typescript
const formValidatorConfig: Partial = {
validateOn: (status) => {
return status.touched || status.submited;
},
};

@NgModule({
imports: [FormValidatorModule.configure(formValidatorConfig)],
})
export class AppModule {}
`

Validators

$3

Wrapped angular built-in validators, that help we can pass the custom validation message to the validator function when creating the form control

See more details in the Angular docs

#### min

Validator that requires the control's value to be greater than or equal to the provided number.

min(min: number, message: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ |
| min | number |
| message | string |

##### Usage:

`typescript
import { min } from '@popeyelab/ngx-validator';

// ...
const control = new FormControl(2, [min(10, 'Value should be greater than or equal to 10')]);
console.log(control.errors); // {min: {min: 10, actual: 2, message: 'Value should be greater than or equal to 10'}}
`

#### max

Validator that requires the control's value to be less than or equal to the provided number.

max(max: number, message: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ |
| max | number |
| message | string |

##### Usage:

`typescript
import { max } from '@popeyelab/ngx-validator';

// ...
const control = new FormControl(20, max(10, 'Value should be less than or equal to 10'));
console.log(control.errors); // {max: {max: 10, actual: 20, message: 'Value should be less than or equal to 10'}}
`

#### required

Validator that requires the control have a non-empty value.

required(message: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ |
| message | string |

##### Usage:

`typescript
import { required } from '@popeyelab/ngx-validator';

// ...
const control = new FormControl('', required('This field is required'));
console.log(control.errors); // {required: {message: 'This field is required'}}
`

#### requiredTrue

Validator that requires the control's value be true. This validator is commonly used for required checkboxes.
requiredTrue(message: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ |
| message | string |

##### Usage:

`typescript
import { requiredTrue } from '@popeyelab/ngx-validator';

// ...
const control = new FormControl(false, requiredTrue('This field is required'));
console.log(control.errors); // {required: {message: 'This field is required'}}
`

#### email

Validator that requires the control's value pass an email validation test.
email(message: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ |
| message | string |

##### Usage:

`typescript
import { email } from '@popeyelab/ngx-validator';

// ...
const control = new FormControl('example email', email('This email is invalid'));
console.log(control.errors); // {email: {message: 'This email is invalid'}}
`

#### minLength

Validator that requires the length of the control's value to be greater than or equal to the provided minimum length.
minLength(minLength: number, message: string): ValidatorFn

##### Parameters

| Name | Type |
| --------- | ------ |
| minLength | number |
| message | string |

##### Usage:

`typescript
import { minLength } from '@popeyelab/ngx-validator';
// ...

const control = new FormControl('hello', minLength(10, 'Should have at least 10 characters'));
console.log(control.errors); // {minlength: {requiredLength: 10, actualLength: 5, message: 'Should have at least 10 characters'}}
`

#### maxLength

Validator that requires the length of the control's value to be less than or equal to the provided maximum length.
maxLength(maxLength: number, message: string): ValidatorFn

##### Parameters

| Name | Type |
| --------- | ------ |
| maxLength | number |
| message | string |

##### Usage:

`typescript
import { maxLength } from '@popeyelab/ngx-validator';
// ...

const control = new FormControl('hello world', maxLength(10, 'The max length of 10 characters is reached'));
console.log(control.errors); // {maxlength: {requiredLength: 10, actualLength: 11, message: 'The max length of 10 characters is reached'}}
`

#### pattern

Validator that requires the control's value to match a regex pattern.
pattern(pattern: string | RegExp, message: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ | ------ |
| pattern | string | RegExp |
| message | string |

##### Usage:

`typescript
import { pattern } from '@popeyelab/ngx-validator';
// ...

const onlyNumber = /^[0-9]+$/;
const control = new FormControl('Hello', pattern(onlyNumber, 'Please input numeric characters only'));

console.log(control.errors); // {pattern: {requiredPattern: '/^[0-9]+$/', actualValue: 'Hello', message: 'Please input numeric characters only'}}
`

$3

Provides a set of common validators that can be used by form controls.

#### range

Validator that requires the control's value to be in the provided range

range(range: [number, number], message: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ---------------- |
| range | [number, number] |
| message | string |

##### Usage:

`typescript
import { range } from '@popeyelab/ngx-validator';

// ...
const [min, max] = [0, 10];
const control = new FormControl(11, range([min, max], 'Value should be in the range of 0 to 10'));
console.log(control.errors); // {range: {range: [0, 10], actual: 11, message: 'Value should be in the range of 0 to 10'}}
`

#### url

Validator that requires the control's value pass an URL.
url(message?: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ |
| message | string |

##### Usage:

`typescript
import { url } from '@popeyelab/ngx-validator';

// ...
const control = new FormControl('example url', url('Invalid URL'));
console.log(control.errors); // {url: {message: 'Invalid URL'}}
`

$3

Validator that requires the control's value equal to the provided value.
equal(value: string, message?: string): ValidatorFn

##### Parameters

| Name | Type |
| ------- | ------ |
| value | string |
| message | string |

##### Usage:

`typescript
import { equal } from '@popeyelab/ngx-validator';

// ...
const control = new FormControl('hello', equal('hello world', 'Value should be equal to hello world'));
`

$3

Validator that requires the control's value equal to the value of provided control.
equalTo(controlNamePath: string, message?: string): ValidatorFn

##### Parameters

| Name | Type |
| --------------- | ------ |
| controlNamePath | string |
| message | string |

##### Usage:

`typescript
import { Component } from '@angular/core';
import { FormControl, FormGroup } from '@angular/forms';
import { equalTo } from '@popeyelab/ngx-validator';

// ...

form = new FormGroup({
password: new FormControl(''),
confirmPassword: new FormControl('', [equalTo('password', 'Confirm Password does not match')]),
});
`

$3

The validator requires that the value of the control not be empty or contain only spaces
noWhitespace(message?: string): ValidatorFn

##### Parameters

| Name | Type |
| --------------- | ------ |
| message | string |

##### Usage:

`typescript
import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';
import { noWhitespace } from '@popeyelab/ngx-validator';

// ...

const control = new FormControl(' ', noWhitespace('This field is required'));
console.log(control.errors); // {required: {message: 'This field is required'}}
``

Back to top

Changelog

See the release page.

License

This project is released under the MIT