NgxFieldValidationErrors 🛠️

Live Demo

NgxFieldValidationErrors is an Angular library that streamlines form validation by automatically managing and displaying error messages for form controls. It works with both template-driven and reactive forms, offering a minimal setup and flexible configuration.

Angular Version Support

📦 Installation

npm install ngx-field-validation-errors
# or
yarn add ngx-field-validation-errors

Include the stylesheet in your angular.json or import directly:

"styles": [
  "node_modules/ngx-field-validation-errors/src/styles/ngx-error.css",
  "src/styles.css"
]

⚙️ Global Configuration (provideNgxFieldValidation)

The library exposes a provider function you add to your application-level providers array. This function accepts an optional IErrorConfig object, which controls default behaviour and templates.

import { provideNgxFieldValidation } from 'ngx-field-validation-errors';

export const appConfig: ApplicationConfig = {
  providers: [
    provideNgxFieldValidation({
      defaultErrorTemplate: true,
      showFieldError: 'single',
      defaultErrorTemplateType: 'plain-text-error',
      errorFieldBorderStyle: 'dashed',
      // you can override or extend templates by supplying keys here
      errorTemplate: {
         // Overrides the default 'required' validation message.
         // Use '{name}' as a placeholder to dynamically inject the field name.
         // Similarly, you can override any built-in validation message
        // (e.g., 'minlength', 'maxlength', 'email', etc.) by providing the corresponding key.
        required: 'Please enter a {name}',

        // Defines a custom validation message for a user-defined validator key.
        // The key ('invalidUsername') should match the validation error returned by the control.
       invalidUsername: 'Username already exists.'
      }
    })
  ]
};

Note: if you omit the errorTemplate property entirely, the built‑in default messages (provided by the library) are used. Supplying your own object simply merges onto the defaults, so you only need to define custom keys or override specific messages.

IErrorConfig fields

| Property | Type | Description | |---------------------------|-----------------------------------------------|-------------| | showFieldError | 'multiple' \| 'single' | Whether to display one message per field or all messages. | | errorFieldBorderStyle? | 'solid' \| 'dashed' \| 'none' | (optional) Border style applied to invalid inputs. | | errorTemplate? | Record<string,string> | IErrorTemplate | (optional) Custom templates keyed by error name. | | defaultErrorTemplate? | boolean | (optional) Render the default error template for fields. | | defaultErrorTemplateType?| 'icon-text-error' \| 'plain-text-error' | (optional) Style of the default template. |

The provider merges the supplied config with library defaults and registers related services (template registry, event plugin, validators).

🔧 Field Directive: ngx-error

Attach this directive to an input or control container to manage error state and optionally render a default message.

Inputs

| Input | Type | Value | Description | |--------------|--------------|---------------|-------------| | ngxError | IFieldConfig | { name: 'field' } | Configuration object controlling how errors are handled for a specific control. The name property is required—users must supply it. See below for fields. |

IFieldConfig properties

| Property | Type | Default | Description | |-------------------------|------------|---------------------|-------------| | name | string | required | {name} as a placeholder to dynamically inject the field name into the error message. | | defaultErrorTemplate | boolean | true | If true, the default template (text or icon) will be rendered for this field. Can override global setting. | | skipOnValidate | boolean | false | When true, this field ignores (click.validate) events, keeping errors hidden until the control is touched/dirty. |

IFieldConfig shape

interface IFieldConfig {
  name: string;               // field name for message
  defaultErrorTemplate?: boolean; // render default template
  skipOnValidate?: boolean;   // ignore validateOnEvent triggers
}

Example

Angular property binding:

<input [ngxError]="{ name: 'Password', defaultErrorTemplate: false }" ... />

Validate event (show all field errors)

If you want errors to appear for every field only when the user attempts to submit, the library supports a simple (click.validate) listener on a button (or any interactive element):

<button (click.validate)="onSubmit()">Submit</button>

Clicking such an element tells all active ngx-error directives to update their messages and display any validation problems. Fields configured with skipOnValidate will ignore these notifications. This pattern keeps the form clean until the user hits the submit control.

No additional setup is required beyond adding the directive to your inputs.

🔁 Component: <ngx-validation-error>

Renders validation messages for a control. It locates error text from the Validation service and supports custom templates.

Inputs & slots

| Input / Template | Type | Description | |-------------------------|---------------------------|-------------| | for | template ref | Identifier passed to the directive or component to resolve errors. | | #customProjectTemplate | <ng-template> | Optional projected template. Receives context { error: string }. |

Usage examples

Basic usage (uses global/default messages):

<input formControlName="email" #email="ngxError" [ngxError]="{ name: 'Email'}" />
<ngx-validation-error [for]="email"></ngx-validation-error>

With a custom template:

<input formControlName="password" #password="ngxError" [ngxError]="{ name: 'Password'}" />
<ngx-validation-error [for]="password">
  <ng-template #customProjectTemplate let-error="error">
    <div class="my-error">
      <i class="fa fa-exclamation-circle"></i> {{ error }}
    </div>
  </ng-template>
</ngx-validation-error>

Global registration of a custom template via ErrorTemplateRegistry can apply to all instances.

To register a template globally you can capture a template reference in a component and then pass it to the registry after view initialization. For example:

import { AfterViewInit, Component, TemplateRef, ViewChild } from '@angular/core';
import { ErrorTemplateRegistry } from 'ngx-field-validation-errors';

@Component({/* ... */})
export class AppComponent implements AfterViewInit {
  @ViewChild('globalCustomErrorTemplate') public errorTemplate!: TemplateRef<any>;

  constructor(private errorTemplateService: ErrorTemplateRegistry) {}

  ngAfterViewInit(): void {
    // registers the template for use by name
    this.errorTemplateService.setErrorUiTemplate(this.errorTemplate);
  }
}

<ng-template #globalCustomErrorTemplate let-error="error">
  <div class="error-text">{{error}} ❗</div>
</ng-template>

Once registered, every <ngx-validation-error> or ngx-error field that requests the corresponding template will render using the shared markup.

📚 Resources

• Angular forms guide: https://angular.io/guide/forms-overview
• Angular CLI: https://angular.io/cli

📜 License

MIT © NgxFieldValidationErrors

👤 Creator

• Name: Shantanu Yewale
• Email: [email protected]
  (Feel free to share any bugs or feedback.)
• LinkedIn: https://www.linkedin.com/in/shantanu-yewale-53a044212/
• Portfolio: https://shantanuyewaledev.netlify.app/

Thanks for using NgxFieldValidationErrors! Contributions and issues are welcome.