ngx-error v0.0.1

Overview

Why use ngx-error, how to install and use.

What is it?

Declarative validation error messages for reactive forms.

Typically you'd do something like this:

<!-- without ngxError -->
<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 ngxError, we've taken a simple declarative approach that cleans up your templates to make validation easier:

<!-- with ngxErrors -->
<input type="text" formControlName="foo">

 <div #input="ngxErrors" ngxErrors="foo">
    <div *ngxError="'required'; when:'touched'">
      Field is required
    </div>
    <div *ngxError="'minlength'; when:'touched'">
      Min length is 5
    </div>
  </div>

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

Installation

yarn add ngx-error

# OR

npm install --save ngx-error

Setup

Just add ngx-error to your module:

import { NgxErrorsModule } from 'ngx-error';

@NgModule({ imports: [ NgxErrorsModule ] })

Documentation

ngxErrors

The ngxError 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>

ngxError #when

The when option 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 ngxErrors="username">
  <div ngxError="'required'; when:'touched'">
    Min length is 5
  </div>
</div>

It also comes in array format for multiple rules:

<input type="text" formControlName="username">
<div ngxErrors="username">
  <div ngxError="'required'; when:['touched', 'dirty']">
    Min length is 5
  </div>
</div>

Nested FormGroup support

ngxErrors also supports FormGroups with control names using dot notation:

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

Exported Directive API

ngx-error exports itself as ngxErrors, which means you can access information about your control error states elsewhere in your template using a template reference, such as #foo.

Basic usage:

<div ngxErrors="username" #myError="ngxErrors"></div>

getError(name: string): any;

The getError method returns the object associated with your error. This can be useful for dynamically displaying error rules.

Example: Adds Min length is 5 when value is less than 5 characters (based on Validators.minLength(5)).

<input type="text" formControlName="username">

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="minlength">
    Min length should be {{ myError.getError('minlength')?.requiredLength }}
  </div>
</div>

The error returned is identical to Angular's FormControl API

hasError(name: string, conditions?: string | string[]): boolean;

The hasError method informs you if your control has the given error. This can be useful for styling elsewhere in your template based off the control's error state.

Example: Adds class="required" when "myError" has the required error.

<div [class.required]="myError.hasError('required')">
  <input type="text" formControlName="username">
</div>

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="required">
    Field is required
  </div>
</div>

You can optionally pass in conditions in which to activate the error.

Example: Adds class="required" when "myError" has the required error and the states are 'dirty' and 'touched'.

<div [class.required]="myError.hasError('required', ['dirty', 'touched'])">
  <input type="text" formControlName="username">
</div>

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="required">
    Field is required
  </div>
</div>

You can also use the "catch-all" selector to get the state of your entire control's validity, alongside on an optional state collection.

<div>
  <div [ngClass]="{
    invalid: myError.hasError('*'),
    invalidTouchedDirty: myError.hasError('*', ['touched', 'dirty'])
  }">
  </div>
  <input type="text" formControlName="username">
</div>

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="required">
    Field is required
  </div>
</div>

isValid(name: string, conditions?: string | string[]): boolean;

The isValid method informs you if a your control is valid, or a property is valid. This can be useful for styling elsewhere in your template based off the control's validity state.

Example: Adds class="valid" when "myError" has no required error.

<div [class.valid]="myError.isValid('required')">
  <input type="text" formControlName="username">
</div>

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="required">
    Field is required
  </div>
</div>

You can optionally pass in conditions in which to evaluate alongside the property you're checking is valid.

Example: Adds class="valid" when "myError" has no required error and the states are 'dirty' and 'touched'.

<div [class.valid]="myError.isValid('required', ['dirty', 'touched'])">
  <input type="text" formControlName="username">
</div>

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="required">
    Field is required
  </div>
</div>

You can also use the "catch-all" selector to check if the control is valid, with no specific error properties, alongside on an optional state collection.

<div>
  <div [ngClass]="{
    valid: myError.isValid('*'),
    validTouchedDirty: myError.isValid('*', ['touched', 'dirty'])
  }">
  </div>
  <input type="text" formControlName="username">
</div>

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="required">
    Field is required
  </div>
</div>

hasErrors: boolean;

The hasErrors property returns true if your control has any number of errors. This can be useful for styling elsewhere in your template on a global control level rather than individual errors.

Example: Adds class="errors" when "myError" has any errors.

<div [class.errors]="myError.hasErrors">
  <input type="text" formControlName="username">
</div>

<div ngxErrors="username" #myError="ngxErrors">
  <div *ngxError="required">
    Field is required
  </div>
  <div *ngxError="minlength">
    Min length is 5
  </div>
</div>

The errors returned are identical to Angular's FormControl API