Note: This package is a fork from @ultimate/ngxerrors. The reason why is because the main package is not maintained anymore. This package supports Angular 6+. Feel free to create issues and pull requests as needed.
Why use ngx-errors, how to install and use.
Declarative validation error messages for reactive forms.
Typically you'd do something like this:
<!-- without ngxErrors -->
<inputtype="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 to make validation easier:
<!-- with ngxErrors -->
<inputtype="text"formControlName="foo"><divngxErrors="foo"><divngxError="required"when="touched">
Field is required
</div><divngxError="minlength"when="dirty">
Min length is 5
</div></div>Check out the documentation below for all the syntax we provide.
yarn add @polarcape/ngxerrors
# OR
npm i @polarcape/ngxerrorsJust add ngx-errors to your module:
import{NgxErrorsModule}from'@polarcape/ngxerrors';
@NgModule({imports: [NgxErrorsModule]})The ngxErrors directive works by dynamically fetching your FormControl under-the-hood, so simply take your formControlName value and pass it into ngxErrors:
<inputtype="text" formControlName="username"><divngxErrors="username">
// ...
</div>This needs to be on a parent container that will encapsulate child ngxError directives.
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":
<inputtype="text" formControlName="username"><divngxErrors="username"><divngxError="minlength">
Min length is 5
</div></div>Note: when using array syntax,
[]bindings are needed
Using the array syntax, when any condition in the array is true the error will be shown:
<inputtype="text" formControlName="username"><divngxErrors="username"><div[ngxError]="['minlength', 'maxlength']">
Min length is 5, max length is 10
</div></div>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":
<inputtype="text" formControlName="username"><divngxErrors="username"><divngxError="minlength" when="dirty">
Min length is 5
</div></div>It also comes in array format for multiple rules:
<inputtype="text" formControlName="username"><divngxErrors="username"><divngxError="minlength" [when]="['dirty', 'touched']">
Min length is 5
</div></div>You can optionally data-bind and dynamically create validation errors with ngxErrors:
<inputtype="text" formControlName="username"><divngxErrors="person.username"><div*ngFor="let error of errors" [ngxError]="error.name" [when]="error.rules">
{{ error.text }}
</div></div>With corresponding component class:
@Component({...})exportclassMyComponent{errors=[{name: 'required',text: 'This field is required',rules: ['touched','dirty']},{name: 'minlength',text: 'Min length is 5',rules: ['dirty']}];}ngxErrors also supports FormGroups with control names using dot notation:
<divformGroupName="person"><inputtype="text" formControlName="username"><divngxErrors="person.username"><divngxError="minlength" [when]="['dirty', 'touched']">
Min length is 5
</div></div></div>ngx-errors 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:
<divngxErrors="username" #myError="ngxErrors"></div>The getError method returns the object associated with your error. This can be useful for dynamically displaying error rules.
Example: Adds
Min length is 5when value is less than 5 characters (based onValidators.minLength(5)).
<inputtype="text" formControlName="username"><divngxErrors="username" #myError="ngxErrors"><divngxError="minlength" when="dirty">
Min length should be {{ myError.getError('minlength')?.requiredLength }}
</div></div>The error returned is identical to Angular's FormControl API
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 therequirederror.
<div[class.required]="myError.hasError('required')"><inputtype="text" formControlName="username"></div><divngxErrors="username" #myError="ngxErrors"><divngxError="required" when="dirty">
Field is required
</div></div>You can optionally pass in conditions in which to activate the error.
Example: Adds
class="required"when "myError" has therequirederror and the states are'dirty'and'touched'.
<div[class.required]="myError.hasError('required', ['dirty', 'touched'])"><inputtype="text" formControlName="username"></div><divngxErrors="username" #myError="ngxErrors"><divngxError="required" when="dirty">
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><inputtype="text" formControlName="username"></div><divngxErrors="username" #myError="ngxErrors"><divngxError="required" when="dirty">
Field is required
</div></div>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 norequirederror.
<div[class.valid]="myError.isValid('required')"><inputtype="text" formControlName="username"></div><divngxErrors="username" #myError="ngxErrors"><divngxError="required" when="dirty">
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 norequirederror and the states are'dirty'and'touched'.
<div[class.valid]="myError.isValid('required', ['dirty', 'touched'])"><inputtype="text" formControlName="username"></div><divngxErrors="username" #myError="ngxErrors"><divngxError="required" when="dirty">
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><inputtype="text" formControlName="username"></div><divngxErrors="username" #myError="ngxErrors"><divngxError="required" when="dirty">
Field is required
</div></div>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"><inputtype="text" formControlName="username"></div><divngxErrors="username" #myError="ngxErrors"><divngxError="required" when="dirty">
Field is required
</div><divngxError="minlength" when="dirty">
Min length is 5
</div></div>The errors property returns the object associated with any active errors. This can be used to access any error properties on your control.
Example: Adds
Max length is 10, you typed (n)when value is more than 10 characters (based onValidators.maxLength(10)).
<inputtype="text" formControlName="username"><divngxErrors="username" #myError="ngxErrors"><divngxError="minlength" when="dirty">...</div><divngxError="maxlength" when="dirty">...</div></div><div*ngIf="myError.errors?.maxlength">
Max length is 10, you typed {{ myError.errors.maxlength.actualLength }}
</div>The errors returned are identical to Angular's FormControl API
Please see the contributing guidelines.