Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/UltimateAngular/ngxerrors

A declarative validation errors module for reactive forms.
https://github.com/UltimateAngular/ngxerrors

angular reactive validation

Last synced: 3 months ago
JSON representation

A declarative validation errors module for reactive forms.

Awesome Lists containing this project

README 

        
[![Build Status][circle-badge]][circle-badge-url]

[![Dependency Status][david-badge]][david-badge-url]

[![devDependency Status][david-dev-badge]][david-dev-badge-url]

[![npm][npm-badge]][npm-badge-url]







ngx-errors



A declarative validation errors module for reactive forms.



---






---





Installation |

Setup |

Documentation |

Live demo




---



# Overview



Why use ngx-errors, how to install and use.



### What is it?



Declarative validation error messages for reactive forms.



Typically you'd do something like this:



```js





  Field is required





  Min length is 5



```



With ngxErrors, we've taken a simple declarative approach that cleans up your templates to make validation easier:



```js





  


    Field is required

  


  


    Min length is 5

  




```



Check out the documentation below for all the syntax we provide.



### Installation



```bash

yarn add @ultimate/ngxerrors



# OR



npm i @ultimate/ngxerrors

```



### Setup



Just add ngx-errors to your module:



```js

import { NgxErrorsModule } from '@ultimate/ngxerrors';



@NgModule({ imports: [ NgxErrorsModule ] })

```



# Documentation



### ngxErrors



The `ngxErrors` directive works by dynamically fetching your FormControl under-the-hood, so simply take your `formControlName` value and pass it into `ngxErrors`:



```html





  // ...



```



This needs to be on a parent container that will encapsulate child `ngxError` directives.



### ngxError



The `ngxError` directive takes either a `string` or `array` as arguments. The argument you pass in corresponds to any active errors exposed on your control, such as "required" or "minlength":



```html





  


    Min length is 5

  




```



> Note: when using array syntax, `[]` bindings are needed



Using the array syntax, when any condition in the array is true the error will be shown:



```html





  


    Min length is 5, max length is 10

  




```



### ngxError #when



The `when` directive takes either a `string` or `array` as arguments. It allows you to specify when you wish to display the error based on the control state, such as "dirty" or "touched":



```html





  


    Min length is 5

  




```



It also comes in array format for multiple rules:



```html





  


    Min length is 5

  




```



### Dynamic errors



You can optionally data-bind and dynamically create validation errors with ngxErrors:



```html





  


    {{ error.text }}

  




```



With corresponding component class:



```js

@Component({...})

export class MyComponent {

  errors = [

    { name: 'required', text: 'This field is required', rules: ['touched', 'dirty'] },

    { name: 'minlength', text: 'Min length is 5', rules: ['dirty'] }

  ];

}

```



### Nested FormGroup support



ngxErrors also supports FormGroups with control names using dot notation:



```html



  

  


    


      Min length is 5

    


  




```



### Exported Directive API



ngx-errors exports itself as `ngxErrors`, which means you can access information about your control error states elsewhere in your template using a template reference, such as `#foo`.



Basic usage:



```html



```



#### getError(name: string): any;



The `getError` method returns the object associated with your error. This can be useful for dynamically displaying error rules.



> Example: Adds `Min length is 5` when value is less than 5 characters (based on `Validators.minLength(5)`).



```html





  


    Min length should be {{ myError.getError('minlength')?.requiredLength }}

  




```



> The error returned is identical to Angular's FormControl API



#### hasError(name: string, conditions?: string | string[]): boolean;



The `hasError` method informs you if your control has the given error. This can be useful for styling elsewhere in your template based off the control's error state.



> Example: Adds `class="required"` when "myError" has the `required` error.



```html



  






  


    Field is required

  




```



You can optionally pass in conditions in which to activate the error.



> Example: Adds `class="required"` when "myError" has the `required` error _and_ the states are `'dirty'` and `'touched'`.



```html



  






  


    Field is required

  




```



You can also use the "catch-all" selector to get the state of your entire control's validity, alongside on an optional state collection.



```html



  


  


  






  


    Field is required

  




```



#### isValid(name: string, conditions?: string | string[]): boolean;



The `isValid` method informs you if a your control is valid, or a property is valid. This can be useful for styling elsewhere in your template based off the control's validity state.



> Example: Adds `class="valid"` when "myError" has no `required` error.



```html



  






  


    Field is required

  




```



You can optionally pass in conditions in which to evaluate alongside the property you're checking is valid.



> Example: Adds `class="valid"` when "myError" has no `required` error _and_ the states are `'dirty'` and `'touched'`.



```html



  






  


    Field is required

  




```



You can also use the "catch-all" selector to check if the control is valid, with no specific error properties, alongside on an optional state collection.



```html



  


  


  






  


    Field is required

  




```



#### hasErrors: boolean;



The `hasErrors` property returns `true` if your control has any number of errors. This can be useful for styling elsewhere in your template on a global control level rather than individual errors.



> Example: Adds `class="errors"` when "myError" has any errors.



```html



  






  


    Field is required

  


  


    Min length is 5

  




```



#### errors: { [key: string]: any; };



The `errors` property returns the object associated with any active errors. This can be used to access any error properties on your control.



> Example: Adds `Max length is 10, you typed (n)` when value is more than 10 characters (based on `Validators.maxLength(10)`).



```html





  
...


  
...







  Max length is 10, you typed {{ myError.errors.maxlength.actualLength }}



```



> The errors returned are identical to Angular's FormControl API



[circle-badge]: https://circleci.com/gh/UltimateAngular/ngxerrors.svg?style=shield

[circle-badge-url]: https://circleci.com/gh/UltimateAngular/ngxerrors

[david-badge]: https://david-dm.org/UltimateAngular/ngxerrors.svg

[david-badge-url]: https://david-dm.org/UltimateAngular/ngxerrors

[david-dev-badge]: https://david-dm.org/UltimateAngular/ngxerrors/dev-status.svg

[david-dev-badge-url]: https://david-dm.org/UltimateAngular/ngxerrors?type=dev

[npm-badge]: https://img.shields.io/npm/v/@ultimate/ngxerrors.svg

[npm-badge-url]: https://www.npmjs.com/package/@ultimate/ngxerrors



# Contributing



Please see the [contributing](CONTRIBUTING.md) guidelines.