NgxMatErrors

What Does It Do?

NgxMatErrors provides an easy yet flexible solution for displaying error messages in a MatFormField.

Try It

See it in action on StackBlitz.

How to Use It

Install ngx-mat-errors in your project:

npm install ngx-mat-errors

Import NgxMatErrorsModule and provide NGX_MAT_ERROR_CONFIG_EN (or your custom error messages) in your app.module.ts.

import { NgxMatErrorsModule, NGX_MAT_ERROR_CONFIG_EN } from "ngx-mat-errors";

@NgModule({
  imports: [
    ...,
    NgxMatErrorsModule
  ],
  providers: [NGX_MAT_ERROR_CONFIG_EN],
})
export class AppModule {}

Or you can import only NgxMatErrors and NgxMatErrorDef as they are marked standalone.

import { NgxMatErrors, NgxMatErrorDef, NGX_MAT_ERROR_CONFIG_EN } from "ngx-mat-errors";

@NgModule({
  imports: [
    ...,
    NgxMatErrors,
    NgxMatErrorDef
  ],
  providers: [NGX_MAT_ERROR_CONFIG_EN],
})
export class AppModule {}

Add [ngx-mat-errors] to your mat-error in your mat-form-field.

  Label
  <input type="text">
  

Outside a MatFormField or Override the Control

ngx-mat-errors can be used as an @Input() to assign a control manually.

Reactive Forms

  Label
  <input autocomplete="off" type="text">

Template-Driven Forms

  Label
  <input autocomplete="off" type="text">

Multiple Controls

It can display errors for multiple controls, one at a time. The order of the controls is important; the first control with an error will be displayed.

  Label
  
    <input>
    <input>
  
  
  

NgxMatErrorsForDateRangePicker Directive

import { NgxMatErrorsForDateRangePicker } from "ngx-mat-errors";

You can use the [forDateRangePicker] standalone directive to display errors for the MatDateRangePicker component. The directive assigns the controls used in the MatDateRangeInput to the NgxMatErrors component.

  Label
  
    <input>
    <input>
  
  
  

You can easily create directives like this to display errors in a MatFormField with multiple controls.

Customize

There are two ways to customize your error messages.

Injection Token

There is the NGX_MAT_ERROR_DEFAULT_OPTIONS injection token. You can provide it in your app.module.ts with useClass or useFactory and customize your error messages globally.

This example changes only the min error message.

import {
  errorMessagesEnFactory,
  NGX_MAT_ERROR_DEFAULT_OPTIONS
} from 'ngx-mat-errors';
import { FactoryProvider, LOCALE_ID } from '@angular/core';

export const NGX_MAT_ERROR_DEFAULT_CONFIG: FactoryProvider = {
  useFactory: (locale: string) => ({
    ...errorMessagesEnFactory(locale),
    min: (error: MinError) =>
      `Min value is ${error.min}, actual is ${error.actual}`,
  }),
  provide: NGX_MAT_ERROR_DEFAULT_OPTIONS,
  deps: [LOCALE_ID],
};

@NgModule({
  ...
  providers: [NGX_MAT_ERROR_DEFAULT_CONFIG],
})
export class AppModule {}

You can provide an Observable too, which allows changes of error messages. This comes in handy when your app supports JIT localization with libraries like @ngx-translate.

import {
  NGX_MAT_ERROR_DEFAULT_OPTIONS
} from 'ngx-mat-errors';
import { FactoryProvider, LOCALE_ID } from '@angular/core';
import { TranslateModule, TranslateService } from '@ngx-translate/core';
import { Observable, startWith, map } from 'rxjs';

export const NGX_MAT_ERROR_DEFAULT_CONFIG: FactoryProvider = {
  useFactory: (
    locale: string,
    translateService: TranslateService
  ): Observable => translateService.onLangChange.pipe(
    startWith(null),
    map(() => ({
      required: translateService.instant('core.validations.required'),
      minlength: (error: MinError) => translateService.instant('core.validations.minlength', error),
      ...
    }))
  ),
  provide: NGX_MAT_ERROR_DEFAULT_OPTIONS,
  deps: [LOCALE_ID, TranslateService],
};

@NgModule({
  ...
  providers: [NGX_MAT_ERROR_DEFAULT_CONFIG],
})
export class AppModule {}

*ngxMatErrorDef

You can customize your error messages even more with the *ngxMatErrorDef directive.

  Label
  <input type="text">
  
    <span> Only digits are allowed, up to 12 digits. </span>
     The minimum value is {{ error.min }}. 
  

When used with multiple controls, you can specify the control for which the error message is intended.

  Label
  
    <input>
    <input>
  
  
  
    <span>Start date is required.</span>
    <span>End date is required.</span>
  

Compatibility

• @angular/core: ^18.0.0 || ^19.0.0
• @angular/material: ^18.0.0 || ^19.0.0

Reactive Forms

Errors Inside a MatFormField

  Label
  <input type="text">
  

Errors Outside a MatFormField

  Label
  <input type="text">

Errors for Multiple Controls

  Label
  
    <input>
    <input>
  
  
  

Template-Driven Forms

Errors Inside a MatFormField

  Label
  <input type="text">
  

Errors Outside a MatFormField

  Label
  <input type="text">

Errors for Multiple Controls

  Label
  
    <input>
    <input>
  
  
  

Development

Library Build / NPM Package

Run npm run develop to build the library and generate an NPM package. The build artifacts will be stored in the dist/ngx-mat-errors folder.

Development Server

Run npm start for a dev server. Navigate to https://localhost:4202/. The app will automatically reload if you change any of the source files.