@ultimate/ngerrors

ngxErrors

A declarative validation module for reactive forms.

Installation | Setup | Documentation | Live demo

Overview

Why use ngxErrors, how to install and include.

What is it?

Form validation made easy for reactive forms. Typically you'd do something like this:

<input type="text" formControlName="foo">
<div *ngIf="form.get('foo').hasError('required') && form.get('foo').touched">
  Field is required
</div>
<div *ngIf="form.get('foo').hasError('minlength') && form.get('foo').dirty">
  Min length is 5
</div>

With ngxErrors, we've taken a simple declarative approach that cleans up your templates:

<input type="text" formControlName="foo">
<div ngxErrors="foo">
  <div ngError="required" when="touched">
    Field is required
  </div>
  <div ngError="minlength" when="dirty">
    Min length is 5
  </div>
</div>

Check out the documentation below for all the syntax we provide.

Installation

yarn add @ultimate/ngxerrors

# OR

npm i @ultimate/ngxerrors

Setup

Just add ngxErrors to your module:

import { NgxErrorsModule } from '@ultimate/ngxerrors';

@NgModule({ imports: [ NgxErrorsModule ] })

Documentation

ngxErrors

The ngxErrors directive works by dynamically fetching your FormControl under-the-hood, so simply take your formControlName value and pass it into ngxErrors:

<input type="text" formControlName="username">
<div ngxErrors="username">
  // ...
</div>

This needs to be on a parent container that will encapsulate child ngxError directives.

ngxError

The ngxError directive takes either a string or array as arguments. The argument you pass in corresponds to any active errors exposed on your control, such as "required" or "minlength":

<input type="text" formControlName="username">
<div ngxErrors="username">
  <div ngxError="minlength">
    Min length is 5
  </div>
</div>

Note: when using array syntax, [] bindings are needed

Using an error, will show the error message when either condition are true:

<input type="text" formControlName="username">
<div ngxErrors="username">
  <div [ngxError]="['minlength', 'maxlength']">
    Min length is 5, max length is 10
  </div>
</div>

ngxError #when

The when directive takes either a string or array as arguments. It allows you to specify when you wish to display the error based on the control state, such as "dirty" or "touched":

<input type="text" formControlName="username">
<div nxgErrors="username">
  <div nxgError="minlength" when="dirty">
    Min length is 5
  </div>
</div>

It also comes in array format for multiple rules:

<input type="text" formControlName="username">
<div nxgErrors="username">
  <div [nxgError]="minlength" [when]="['dirty', 'touched']">
    Min length is 5
  </div>
</div>

Dynamic errors

You can optionally data-bind and dynamically create validation errors with nxgErrors:

<input type="text" formControlName="username">
<div nxgErrors="person.username">
  <div *ngFor="let error of errors" [nxgError]="error.name" [when]="error.rules">
    {{ error.text }}
  </div>
</div>

With corresponding component class:

@Component({...})
export class MyComponent {
  errors = [
    { name: 'required', text: 'This field is required', rules: ['touched', 'dirty'] },
    { name: 'minlength', text: 'Min length is 5', rules: ['dirty'] }
  ];
}

Nested FormGroup support

nxgErrors also supports FormGroups with control names using dot notation:

<div formGroupName="person">
  <input type="text" formControlName="username">
  <div nxgErrors="person.username">
    <div nxgError="minlength" [when]="['dirty', 'touched']">
      Min length is 5
    </div>
  </div>
</div>

Contributing

Please see the contributing guidelines.