New in ngx-errors 4.0

The @ngspot/ngx-errors library makes it easy to provide validation error messages in apps. The 4.0 release includes 3 large breaking changes:

1. The library has undergone a large internal implementation rewrite making use of Angular signals and is now expected to be used together with Angular >17.1.
2. The library moved away from using NgModules. All directives in the library are now standalone. The directives are available in the consuming applications through exported the NGX_ERRORS_DECLARATIONS variable.
3. The ngxError directive is now expected to be used as a structural directive. This causes a potential breaking change in behavior. In the previous version, the HTML element that the ngxError directive was applied to was always in the DOM. When the error was supposed to be invisible, the hidden attribute was applied to that HTML element. With the new behavior, the DOM associated with the ngxError directive gets completely removed when the error is supposed to be invisible.

Here is an example of using the new version of ngx-errors:

import { NGX_ERRORS_DECLARATIONS } from '@ngspot/ngx-errors';

@Component({
  selector: 'my-component',
  standalone: true,
  imports: [FormsModule, NGX_ERRORS_DECLARATIONS],
  template: `
    <input [(ngModel)]="email" #emailModel="ngModel" required type="email" />

    <div [ngxErrors]="emailModel.control">
      <div *ngxError="'required'">Email is required</div>
    </div>
  `,
})
export class MyComponent implements OnInit {
  email: string;
}

Since the new version of the library does not rely on NgModules, a utility function was introduced to provide library configuration object. The utility function can be used either at the application level or at the component level:

import { provideNgxErrorsConfig } from '@ngspot/ngx-errors';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgxErrorsConfig({
      showErrorsWhenInput: 'dirty',
      showMaxErrors: 1,
    })
  ]
});

For more info and usage examples, see the README file. See the demo here.

The @ngspot/ngx-errors-material 4.0 package has undergone a similar set of changes. The directives are now standalone and are available through the NGX_ERRORS_MATERIAL_DECLARATIONS variable. These declarations include declarations from NGX_ERRORS_DECLARATIONS so no need to import these separately.

The new release also includes one major feature. When using the ngxError directive inside of the <mat-form-field> component, there is no need to include a parent ngxErrors directive. The <mat-form-field> component serves the purpose of ngxErrors directive.

See the example below:

import { NGX_ERRORS_MATERIAL_DECLARATIONS } from '@ngspot/ngx-errors-material';

@Component({
  selector: 'my-component',
  standalone: true,
  imports: [
    ReactiveFormsModule,
    MatInputModule,
    NGX_ERRORS_MATERIAL_DECLARATIONS,
  ],
  template: `
    <form [formGroup]="form">
      <mat-form-field>
        <mat-label>Name</mat-label>

        <input matInput formControlName="name" />

        <mat-error *ngxError="'required'">Name is required</mat-error>
      </mat-form-field>
    </form>
  `
})
export class MyComponent {
  private fb = inject(FormBuilder);

  form = this.fb.group({
    name: this.fb.control('', { validators: [Validators.required] }),
  });
}

See the demo here.

Happy programming!

👏 Special thanks to @anaboca for reviewing this article.