ngx-form-errors
UI Agnostic, @angular/forms
error rendering management utility.
- Does not enforce UI, elements, structure or styles. Just renders.
- Supports Template-Driven Forms and Reactive Forms
- i18n ready architecture
- Default error message
- Customizable
- Cascading configuration
Install
npm install ngx-form-errors
Quick start
In your application root module definition add NgxFormErrorsModule
:
; // lots of code...
You can also set default error messages:
;
Default error messages are only used when error returns
true
instead of a string. An example is the built inrequired
validator.
Create a global error template in the template of the application's root component:
Bootstrap example:
{{item.message}} <!-- COMPONENT TEMPLATE HERE... -->
Material example:
{{item.message}} <!-- COMPONENT TEMPLATE HERE... -->
This template contains the instructions for how to render an error. You can supply any template, the library does not care.
Now, in your forms set error components and attach them to controls:
Template Driven example:
Name
Reactive example:
Name
Reactive example with material design:
Name
In material, the presence of
md-error
is important, it must exists next to the control. This is why<md-error ngxErrors="name"></md-error>
is used, however the actual rendered errors are based on the template!
Advanced features:
Configuration: Error templates comes with a declarative API to customise the behaviour. Things like maximum errors to display, the order of display, render predicate and more... These are all sugar helpers and can be done manually within your templates. Read more in the documentation...
Multiple error template: Supplying one template is enough for most use cases. However, some scenarios requires custom templates. ngx-form-errors support multiple templates using hierarchy.
A template can be set per:
- NgModule
- Component
- NgForm
- Error component content
When the library looks up for a template to use, the closest template to the element is selected (bottom first in the list).
The hierarchy is managed via DOM structure (Error component content & NgForm) and angular's DI for Component & NgModule.
Read more in the documentation for NgxErrorTemplateDirective
Avoid complex configurations
Using multiple error templates with complex hierarchy might get really complex.
Try to avoid complex setups as they are hard to debug.
Here are some options:
- Use custom templates on the component and not through error template even if you repeat it once or twice. When repetition has volume use a template.
- Use control flow within templates (ngIf, ngSwitch) so a template can handle more then 1 scenario.
Examples:
Take a look at the demo app where you can find examples by feature, Reactive Forms example and a Template Driven forms example
Why
Rendering @angular/forms
errors is usually a simple task but one that
repeats itself over and over.
When things spice up, any they always do, it gets more verbose: A control with multiple validators requires an error component for each validator so the error (if exists) coming from a validator will display.
A Form with 3 fields, each with 3 validators required 9 components!
And we're not done, rendering an error is usually done under some restrictions (conditions), most likely based on the control state (dirty, touched, etc) this adds more declarative template code.