Improve overall data quality by validating user input for accuracy and completeness.
This cookbook shows how to validate user input in the UI and display useful validation messages using first the template-driven forms and then the reactive forms approach.
- Simple template-driven forms
- Template-driven forms with validation messages in code
- Reactive forms with validation in code
- Custom validation
- Testing considerations
Try the live example to see and download the full cookbook source code.
Simple template-driven forms
In the template-driven approach, you arrange form elements in the component's template.
You add Angular form directives (mostly directives beginning
ng...) to help
Angular construct a corresponding internal control model that implements form functionality.
In template-drive forms, the control model is implicit in the template.
To validate user input, you add HTML validation attributes to the elements. Angular interprets those as well, adding validator functions to the control model.
Angular exposes information about the state of the controls including whether the user has "touched" the control or made changes and if the control values are valid.
In this first template validation example, notice the HTML that reads the control state and updates the display appropriately. Here's an excerpt from the template HTML for a single input control bound to the hero name:
Note the following:
<input>element carries the HTML validation attributes:
nameattribute of the input is set to
"name"so Angular can track this input element and associate it with an Angular form control called
namein its internal control model.
[(ngModel)]directive allows two-way data binding between the input box to the
The template variable (
#name) has the value
ngModel). This gives you a reference to the Angular
NgModeldirective associated with this control that you can use in the template to check for control states such as
<div>element reveals a set of nested message
divsbut only if there are "name" errors and the control is either
<div>can present a custom message for one of the possible validation errors. There are messages for
The full template repeats this kind of layout for each data entry control on the form.
Why check dirty and touched?
The app shouldn't show errors for a new hero before the user has had a chance to edit the value.
The checks for
touched prevent premature display of errors.
touched in the Forms guide.
The component class manages the hero model used in the data binding as well as other code to support the view.
Use this template-driven validation technique when working with static forms with simple, standard validation rules.
Here are the complete files for the first version of
HeroFormTemplateCompononent in the template-driven approach:
Template-driven forms with validation messages in code
While the layout is straightforward, there are obvious shortcomings with the way it's handling validation messages:
It takes a lot of HTML to represent all possible error conditions. This gets out of hand when there are many controls and many validation rules.
The messages are static strings, hard-coded into the template. It's easier to maintain dynamic messages in the component class.
In this example, you can move the logic and the messages into the component with a few changes to the template and component.
Here's the hero name again, excerpted from the revised template (Template 2), next to the original version:
<input> element HTML is almost the same. There are noteworthy differences:
The hard-code error message
There's a new attribute,
forbiddenName, that is actually a custom validation directive. It invalidates the control if the user enters "bob" in the name
<input>(try it). See the custom validation section later in this cookbook for more information on custom validation directives.
#nametemplate variable is gone because the app no longer refers to the Angular control for this element.
Binding to the new
formErrors.nameproperty is sufficent to display all name validation error messages.
The original component code for Template 1 stayed the same; however, Template 2 requires some changes in the component. This section covers the code necessary in Template 2's component class to acquire the Angular form control and compose error messages.
The first step is to acquire the form control that Angular created from the template by querying for it.
Look back at the top of the component template at the
#heroForm template variable in the
heroForm variable is a reference to the control model that Angular derived from the template.
Tell Angular to inject that model into the component class's
currentForm property using a
@ViewChildqueries for a template variable when you pass it the name of that variable as a string (
'heroForm'in this case).
heroFormobject changes several times during the life of the component, most notably when you add a new hero. Periodically inspecting it reveals these changes.
Angular calls the
ngAfterViewCheckedlifecycle hook method when anything changes in the view. That's the right time to see if there's a new
When there is a new
formChanged()subscribes to its
valueChangesObservable property. The
onValueChangedhandler looks for validation errors after every keystroke.
onValueChanged handler interprets user data entry.
data object passed into the handler contains the current element values.
The handler ignores them. Instead, it iterates over the fields of the component's
formErrors is a dictionary of the hero fields that have validation rules and their current error messages.
Only two hero properties have validation rules,
The messages are empty strings when the hero data are valid.
For each field, the
onValueChanged handler does the following:
- Clears the prior error message, if any.
- Acquires the field's corresponding Angular form control.
- If such a control exists and it's been changed ("dirty") and it's invalid, the handler composes a consolidated error message for all of the control's errors.
Next, the component needs some error messages of course—a set for each validated property with one message per validation rule:
Now every time the user makes a change, the
onValueChanged handler checks for validation errors and produces messages accordingly.
The benefits of messages in code
Clearly the template got substantially smaller while the component code got substantially larger. It's not easy to see the benefit when there are just three fields and only two of them have validation rules.
Consider what happens as the number of validated
fields and rules increases.
In general, HTML is harder to read and maintain than code.
The initial template was already large and threatening to get rapidly worse
with the addition of more validation message
After moving the validation messaging to the component, the template grows more slowly and proportionally. Each field has approximately the same number of lines no matter its number of validation rules. The component also grows proportionally, at the rate of one line per validated field and one line per validation message.
Both trends are manageable.
Now that the messages are in code, you have more flexibility and can compose messages more efficiently. You can refactor the messages out of the component, perhaps to a service class that retrieves them from the server. In short, there are more opportunities to improve message handling now that text and logic have moved from template to code.
FormModule and template-driven forms
Angular has two different forms modules—
ReactiveFormsModule—that correspond with the
two approaches to form development. Both modules come
from the same
@angular/forms library package.
You've been reviewing the "Template-driven" approach which requires the
Here's how you imported it in the
This guide hasn't talked about the
SharedModule or its
SubmittedComponent which appears at the bottom of every
form template in this cookbook.
They're not germane to the validation story. Look at the live example if you're interested.
Reactive forms with validation in code
In the template-driven approach, you markup the template with form elements, validation attributes,
ng... directives from the Angular
At runtime, Angular interprets the template and derives its form control model.
Reactive Forms takes a different approach.
You create the form control model in code. You write the template with form elements
form... directives from the Angular
At runtime, Angular binds the template elements to your control model based on your instructions.
This approach requires a bit more effort. You have to write the control model and manage it.
This allows you to do the following:
- Add, change, and remove validation functions on the fly.
- Manipulate the control model dynamically from within the component.
- Test validation and control logic with isolated unit tests.
The following cookbook sample re-writes the hero form in reactive forms style.
Switch to the ReactiveFormsModule
The reactive forms classes and directives come from the Angular
ReactiveFormsModule, not the
The application module for the reactive forms feature in this sample looks like this:
The reactive forms feature module and component are in the
Focus on the
HeroFormReactiveComponent there, starting with its template.
Begin by changing the
<form> tag so that it binds the Angular
formGroup directive in the template
heroForm property in the component class.
heroForm is the control model that the component class builds and maintains.
Next, modify the template HTML elements to match the reactive forms style. Here is the "name" portion of the template again, revised for reactive forms and compared with the template-driven version:
Key changes are:
The validation attributes are gone (except
required) because validating happens in code.
requiredremains, not for validation purposes (that's in the code), but rather for css styling and accessibility.
A future version of reactive forms will add the
required HTML validation attribute to the DOM element
(and perhaps the
aria-required attribute) when the control has the
required validator function.
Until then, apply the
required attribute and add the
to the control model, as you'll see below.
nameattribute; it serves the same purpose of correlating the input with the Angular form control.
[(ngModel)]binding is gone. The reactive approach does not use data binding to move data into and out of the form controls. That's all in code.
The retreat from data binding is a principle of the reactive paradigm rather than a technical limitation.
The component class is now responsible for defining and managing the form control model.
Angular no longer derives the control model from the template so you can no longer query for it.
You can create the Angular form control model explicitly with
the help of the
Here's the section of code devoted to that process, paired with the template-driven code it replaces:
FormBuilderin a constructor.
buildFormmethod in the
ngOnInitlifecycle hook method because that's when you'll have the hero data. Call it again in the
A real app would retrieve the hero asynchronously from a data service, a task best performed in the
buildFormmethod uses the
fb, to declare the form control model. Then it attaches the same
onValueChangedhandler (there's a one line difference) to the form's
valueChangesevent and calls it immediately to set error messages for the new control model.
FormBuilder declaration object specifies the three controls of the sample's hero form.
Each control spec is a control name with an array value. The first array element is the current value of the corresponding hero field. The optional second value is a validator function or an array of validator functions.
Most of the validator functions are stock validators provided by Angular as static methods of the
Angular has stock validators that correspond to the standard HTML validation attributes.
forbiddenNames validator on the
"name" control is a custom validator,
discussed in a separate section below.
Learn more about
FormBuilder in the Introduction to FormBuilder section of Reactive Forms guide.
Committing hero value changes
In two-way data binding, the user's changes flow automatically from the controls back to the data model properties. Reactive forms do not use data binding to update data model properties. The developer decides when and how to update the data model from control values.
This sample updates the model twice:
- When the user submits the form.
- When the user adds a new hero.
onSubmit() method simply replaces the
hero object with the combined values of the form:
This example is lucky in that the
heroForm.value properties just happen to
correspond exactly to the hero data object properties.
addHero() method discards pending changes and creates a brand new
hero model object.
Then it calls
buildForm() again which replaces the previous
heroForm control model with a new one.
[formGroup] binding refreshes the page with the new control model.
Here's the complete reactive component file, compared to the two template-driven component files.
Run the live example to see how the reactive form behaves, and to compare all of the files in this cookbook sample.
This cookbook sample has a custom
forbiddenNamevalidator() function that's applied to both the
template-driven and the reactive form controls. It's in the
and declared in the
The function is actually a factory that takes a regular expression to detect a specific forbidden name and returns a validator function.
In this sample, the forbidden name is "bob"; the validator rejects any hero name containing "bob". Elsewhere it could reject "alice" or any name that the configuring regular expression matches.
forbiddenNameValidator factory returns the configured validator function.
That function takes an Angular control object and returns either
null if the control value is valid or a validation error object.
The validation error object typically has a property whose name is the validation key,
and whose value is an arbitrary dictionary of values that you could insert into an error message (
Custom validation directive
In the reactive forms component, the
'name' control's validator function list
forbiddenNameValidator at the bottom.
In the template-driven example, the
<input> has the selector (
of a custom attribute directive, which rejects "bob".
ForbiddenValidatorDirective is a wrapper around the
forms recognizes the directive's role in the validation process because the directive registers itself
NG_VALIDATORS provider, a provider with an extensible collection of validation directives.
Here is the rest of the directive to help you get an idea of how it all comes together:
If you are familiar with Angular validations, you may have noticed
that the custom validation directive is instantiated with
useClass. The registered validator must be this instance of
ForbiddenValidatorDirective—the instance in the form with
forbiddenName property bound to “bob". If you were to replace
useClass, then you’d be registering a new class instance, one that
doesn’t have a
To see this in action, run the example and then type “bob” in the name of Hero Form 2.
Notice that you get a validation error. Now change from
useClass and try again.
This time, when you type “bob”, there's no "bob" error message.
For more information on attaching behavior to elements, see Attribute Directives.
You can write isolated unit tests of validation and control logic in Reactive Forms.
Isolated unit tests probe the component class directly, independent of its interactions with its template, the DOM, other dependencies, or Angular itself.
Such tests have minimal setup, are quick to write, and easy to maintain.
They do not require the
Angular TestBed or asynchronous testing practices.
That's not possible with template-driven forms.
The template-driven approach relies on Angular to produce the control model and
to derive validation rules from the HTML validation attributes.
You must use the
Angular TestBed to create component test instances,
write asynchronous tests, and interact with the DOM.
While not difficult, this takes more time, work and skill—factors that tend to diminish test code coverage and quality.