@ngspot/ngx-errors

Reactive forms validation for pros

I solely missed ng-messages directive from AngularJs, so I created this one to use in Angular 2+. In contrast to the one from AngularJs, this one requires you to pass the control name to the directive, instead of its errors. This allowed me to hook in to the status of control, like its dirty state, and display validation messages according to that status. A nice side effect of that decision is less boilerplate code.

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 your application module:

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

@NgModule({
  imports: [
    NgxErrorsModule, // <-- include it in your 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

You configure when to show messages for your 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 your config

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

Here's 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

Just include something similar to the following in your global css file:

[ngxerrors] {
  color: red;
}

Development

Basic Workflow

• Develop
• Write specs
• Run npm run test:lib,
• Run npm run commit, and choose fix or feature
• Run npm run release
• Run npm run build:lib
• 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!