What’s new in ngspot/ngx-errors 3.1.3?

🚀 Feature 1: integration with @angular/material

@ngspot/ngx-errors is a library that makes it easy to provide validation error messages in apps. The 3.1.3 release takes this functionality a step further for applications that use @angular/material.

Let's say that there is an application where the errors are configured to only show to the users when the form is submitted:

	NgxErrorsModule.configure({
	showErrorsWhenInput: 'formIsSubmitted',
	}),

view raw what-new-ngx-errors-01.ts hosted with ❤ by GitHub

… and there is a component that uses a FormGroup inside of a template that has an Angular Material input within the form field with corresponding validation error:

	@Component({
	selector: 'app-home',
	template: `
	<form [formGroup]="myForm">
	<mat-form-field>
	<mat-label>Name</mat-label>
	<input matInput formControlName="description" />
	<mat-error ngxErrors="description">
	<span ngxError="minlength">
	Name should be at least 20 chars
	</span>
	</mat-error>
	</mat-form-field>
	</form>
	`,
	styleUrls: ['./home.component.scss'],
	changeDetection: ChangeDetectionStrategy.OnPush,
	})
	export class HomeComponent {
	myForm = new FormGroup({
	description: new FormControl('', Validators.minLength(20)),
	});
	}

view raw what-new-ngx-errors-02.ts hosted with ❤ by GitHub

Everything is straightforward, however, if the user types something in the input and clicks away, the input gets highlighted red, but the error message isn’t shown!

It makes sense that the error message isn’t shown — the application was configured to show errors only when the form is submitted. So why is input getting highlighted prematurely? Turns out, Material Inputs has its own logic that determines when inputs are in an error state. By default, the input enters an error state when it’s “touched”. This is lucky because ngx-errors has the same default, but the moment the developer wants to customize behavior, things get out of sync.

Version 3.1.3 synchronizes the input error state with the errors actually shown to the user. The input will only get highlighted if there are errors shown to the user.

🚀Feature 2: Custom error state matchers

The @angular/material team has done a great job designing the API for errorStateMatcher. This API has the ability to provide a global errorStateMatcher or override it via an @Input at the level giving the developer a good amount of flexibility.

@ngspot/ngxerrors also provides flexibility to the developer since it is possible to provide a global configuration for when to show the errors as well as override it at lower levels — in the component templates where ngxErrors and ngxError directives are used. Here’s an example of this functionality from the docs:

	<div ngxErrors="control" showWhen="touchedAndDirty">
	<div ngxError="required" showWhen="dirty">
	This will be shown when control is dirty
	</div>
	<div ngxError="min">
	This will be shown when control is touched and dirty
	</div>
	</div>

view raw what-new-ngx-errors-03.html hosted with ❤ by GitHub

The showWhen input would allow the developer to override the default configuration. However, in the previous versions, the developer could only use set values for the showWhen input: 'touched' 'dirty' 'touchedAndDirty' and 'formIsSubmitted' .

With the release of version 3.1.3, the developer can now provide their configurations. See the docs for more info.

🚀Feature 3: new config option — showMaxErrors

Finally, the icing on the cake — a new configuration option that enables developers to configure how many total errors are allowed to be displayed per the ngxErrors block at the same time.

Imagine that the form control has multiple validation rules associated with it — a pretty common scenario. Here’s how the template would look:

	<mat-form-field appearance="fill">
	<mat-label>Some Description</mat-label>
	<input matInput formControlName="description" autocomplete="off" />
	<mat-error ngxErrors="description">
	<span ngxError="minlength">Description should be at least 20 chars</span>
	<span ngxError="test">Description should not have "test" in it</span>
	<span ngxError="life">Please reconsider your life choices!</span>
	</mat-error>
	</mat-form-field>

view raw what-new-ngx-errors-04.html hosted with ❤ by GitHub

It is possible that these validation rules would be invalid at the same time, in which case, all error messages would be displayed to the user:

This by itself does not sound like the end of the world. However, it gets ugly real fast if another input is added below the first one:

The problem has to do with the implementation of the current styles. There’s been an open issue about it since 2017! And that’s why open source is great— people have been coming up with great workarounds for this issue. A developer could choose any of these or use the showMaxErrors configuration option of @ngspot/ngx-errors to only display one error at a time. This might be a good option if you’d like to ease the cognitive load on your users.

I wish you happy programming!

👏 Special thanks to Ana Boca for reviewing, testing, and providing some of the code for this article.