AnaBoca/ngx-errors

Angular directives for displaying validation errors

Reactive forms validation for pros

I very much missed the ng-messages directive from AngularJS, so I created a similar set of directives to use in Angular 2+. In contrast to the directives from AngularJS, the directives in this library require passing the control name to the directive, instead of the control's errors. This allowed me to hook into the status of control, such as its dirty state, and display validation messages according to that status. The design of this library promotes less boilerplate code, which keeps your templates clean.

Features

• ✅ Simple syntax that reduces boilerplate
• ✅ Configure when to display error messages for an app further reducing boilerplate
• ✅ Seamless integration with Reactive Forms
• ✅ Works with nested forms

Table of Contents

• Installation
• Usage
• Advanced configuration
• Styling
• Development

Installation

NPM

npm install @ngspot/ngx-errors

Yarn

yarn add @ngspot/ngx-errors

Usage

Import library into application module:

import { NgxErrorsModule } from '@ngspot/ngx-errors'; // <-- import the module

@NgModule({
  imports: [
    NgxErrorsModule, // <-- include imported module in app module
  ],
})
export class MyAppModule {}

Use case with a form:

@Component({
  selector: 'my-component',
  template: `
    <form [formGroup]="myForm">
      <input formControlName="email" type="email" />

      <div ngxErrors="email">
        <div ngxError="required">Email is required</div>
      </div>
    </form>
  `,
})
export class MyComponent implements OnInit {
  myForm: FormGroup;

  constructor(private fb: FormBuilder) {
    this.myForm = this.fb.group({
      email: ['', Validators.required],
    });
  }
}

Use case with a simple FormControl:

@Component({
  selector: 'my-component',
  template: `
    <input [formControl]="email" placeholder="Email" type="email" />

    <div [ngxErrors]="email">
      <div ngxError="required">Email is required</div>
    </div>
  `,
})
export class MyComponent implements OnInit {
  email = new FormControl('', Validators.required);
}

Configuration

Configure when to show messages for whole module by using .configure() method:

@NgModule({
  imports: [
    NgxErrorsModule.configure({ ... }) // <- provide configuration here
  ],
})
export class MyAppModule {}

Alternatively, use dependency injection to provide configuration at a component level:

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

const myConfig = { ... }; // <- specify config

@Component({
  ...
  providers: [
    { provide: ErrorsConfiguration, useValue: myConfig }
  ]
})
export class MyComponent { }

Here's the configuration object interface:

interface IErrorsConfiguration {
  /**
   * Configure errors to show only when the corresponding input is dirty.
   *
   * Default is `true`.
   */
  showErrorsOnlyIfInputDirty?: boolean;

  /**
   * Configure errors to show only when form is submitted.
   * Upon form submission shows errors even if `showErrorsOnlyIfInputDirty = true`
   * and some of the inputs aren't dirty.
   * Takes effect only when ngxErrors directive is a child of a form.
   *
   * Default is `false`.
   */
  showErrorsWhenFormSubmitted?: boolean;
}

Styling

Include something similar to the following in global CSS file:

[ngxerrors] {
  color: red;
}

Development

Basic Workflow

1. Develop
2. Write specs
3. Run npm run test:lib
4. Run npm run commit and choose fix or feature
5. Run npm run release
6. Run npm run build:lib
7. Go to the dist directory and run npm publish

Scripts

• build:lib - Builds the library
• test:lib - Runs tests
• test:lib:headless - Runs tests in headless mode with Chrome
• release - Releases a new version; this will bump the library's version and update the CHANGE_LOG file based on the commit message
• release:first - Creates the first release
• commit - Creates a new commit message based on Angular commit messgae convention
• contributors:add - Adds a new contributor to the README file

License

MIT © Dmitry Efimenko

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!