Form Validation

We can improve overall data quality by validating user input for accuracy and completeness.

In this cookbook we show 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.

Learn more about these choices in the Forms chapter.

Table of Contents

Simple Template-Driven Forms

Template-Driven Forms with validation messages in code

Reactive Forms with validation in code

Custom validation

Testing

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. We say that 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 the first template validation example, we add more HTML to read that control state and update the display appropriately. Here's an excerpt from the template html for a single input box control bound to the hero name:

template/hero-form-template1.component.html (Hero name)

<label for="name">Name</label> <input type="text" id="name" class="form-control" required minlength="4" maxlength="24" name="name" [(ngModel)]="hero.name" #name="ngModel" > <div *ngIf="name.errors && (name.dirty || name.touched)" class="alert alert-danger"> <div [hidden]="!name.errors.required"> Name is required </div> <div [hidden]="!name.errors.minlength"> Name must be at least 4 characters long. </div> <div [hidden]="!name.errors.maxlength"> Name cannot be more than 24 characters long. </div> </div>

Note the following:

The full template repeats this kind of layout for each data entry control on the form.

Why check dirty and touched?

We shouldn't show errors for a new hero before the user has had a chance to edit the value. The checks for dirty and touched prevent premature display of errors.

Learn about dirty and touched in the Forms chapter.

The component class manages the hero model used in the data binding as well as other code to support the view.

template/hero-form-template1.component.ts (class)

export class HeroFormTemplate1Component { powers = ['Really Smart', 'Super Flexible', 'Weather Changer']; hero = new Hero(18, 'Dr. WhatIsHisWayTooLongName', this.powers[0], 'Dr. What'); submitted = false; onSubmit() { this.submitted = true; } addHero() { this.hero = new Hero(42, '', ''); } }

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:

<div class="container"> <div [hidden]="submitted"> <h1>Hero Form 1 (Template)</h1> <form #heroForm="ngForm" *ngIf="active" (ngSubmit)="onSubmit()"> <div class="form-group"> <label for="name">Name</label> <input type="text" id="name" class="form-control" required minlength="4" maxlength="24" name="name" [(ngModel)]="hero.name" #name="ngModel" > <div *ngIf="name.errors && (name.dirty || name.touched)" class="alert alert-danger"> <div [hidden]="!name.errors.required"> Name is required </div> <div [hidden]="!name.errors.minlength"> Name must be at least 4 characters long. </div> <div [hidden]="!name.errors.maxlength"> Name cannot be more than 24 characters long. </div> </div> </div> <div class="form-group"> <label for="alterEgo">Alter Ego</label> <input type="text" id="alterEgo" class="form-control" name="alterEgo" [(ngModel)]="hero.alterEgo" > </div> <div class="form-group"> <label for="power">Hero Power</label> <select id="power" class="form-control" name="power" [(ngModel)]="hero.power" required #power="ngModel" > <option *ngFor="let p of powers" [value]="p">{{p}}</option> </select> <div *ngIf="power.errors && power.touched" class="alert alert-danger"> <div [hidden]="!power.errors.required">Power is required</div> </div> </div> <button type="submit" class="btn btn-default" [disabled]="!heroForm.form.valid">Submit</button> <button type="button" class="btn btn-default" (click)="addHero()">New Hero</button> </form> </div> <hero-submitted [hero]="hero" [(submitted)]="submitted"></hero-submitted> </div> import { Component } from '@angular/core'; import { Hero } from '../shared/hero'; @Component({ moduleId: module.id, selector: 'hero-form-template1', templateUrl: 'hero-form-template1.component.html' }) export class HeroFormTemplate1Component { powers = ['Really Smart', 'Super Flexible', 'Weather Changer']; hero = new Hero(18, 'Dr. WhatIsHisWayTooLongName', this.powers[0], 'Dr. What'); submitted = false; onSubmit() { this.submitted = true; } addHero() { this.hero = new Hero(42, '', ''); } }

Template-Driven Forms with validation messages in code

While the layout is straightforward, there are obvious shortcomings with the way we handle validation messages:

We 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:

<label for="name">Name</label> <input type="text" id="name" class="form-control" required minlength="4" maxlength="24" forbiddenName="bob" name="name" [(ngModel)]="hero.name" > <div *ngIf="formErrors.name" class="alert alert-danger"> {{ formErrors.name }} </div> <label for="name">Name</label> <input type="text" id="name" class="form-control" required minlength="4" maxlength="24" name="name" [(ngModel)]="hero.name" #name="ngModel" > <div *ngIf="name.errors && (name.dirty || name.touched)" class="alert alert-danger"> <div [hidden]="!name.errors.required"> Name is required </div> <div [hidden]="!name.errors.minlength"> Name must be at least 4 characters long. </div> <div [hidden]="!name.errors.maxlength"> Name cannot be more than 24 characters long. </div> </div>

The <input> element HTML is almost the same. There are noteworthy differences:

Component class

The original component code stays the same. We added new code 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 where we set the #heroForm template variable in the <form> element:

template/hero-form-template1.component.html (form tag)

<form #heroForm="ngForm" *ngIf="active" (ngSubmit)="onSubmit()">

The heroForm variable is a reference to the control model that Angular derived from the template. We tell Angular to inject that model into the component class's currentForm property using a @ViewChild query:

template/hero-form-template2.component.ts (heroForm)

heroForm: NgForm; @ViewChild('heroForm') currentForm: NgForm; ngAfterViewChecked() { this.formChanged(); } formChanged() { if (this.currentForm === this.heroForm) { return; } this.heroForm = this.currentForm; if (this.heroForm) { this.heroForm.valueChanges .subscribe(data => this.onValueChanged(data)); } }

Some observations:

template/hero-form-template2.component.ts (handler)

onValueChanged(data?: any) { if (!this.heroForm) { return; } const form = this.heroForm.form; for (const field in this.formErrors) { // clear previous error message (if any) this.formErrors[field] = ''; const control = form.get(field); if (control && control.dirty && !control.valid) { const messages = this.validationMessages[field]; for (const key in control.errors) { this.formErrors[field] += messages[key] + ' '; } } } } formErrors = { 'name': '', 'power': '' };

The onValueChanged handler interprets user data entry. The 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 object.

The formErrors is a dictionary of the hero fields that have validation rules and their current error messages. Only two hero properties have validation rules, name and power. The messages are empty strings when the hero data are valid.

For each field, the handler

We'll need some error messages of course, a set for each validated property, one message per validation rule:

template/hero-form-template2.component.ts (messages)

validationMessages = { 'name': { 'required': 'Name is required.', 'minlength': 'Name must be at least 4 characters long.', 'maxlength': 'Name cannot be more than 24 characters long.', 'forbiddenName': 'Someone named "Bob" cannot be a hero.' }, 'power': { 'required': 'Power is required.' } };

Now every time the user makes a change, the onValueChanged handler checks for validation errors and produces messages accordingly.

Is this an improvement?

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 we increase the number of validated fields and rules. In general, HTML is harder to read and maintain than code. The initial template was already large and threatening to get rapidly worse as we add more validation message <divs>.

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, we have more flexibility. We can compose messages more intelligently. We 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 — FormsModule and ReactiveFormsModule — that correspond with the two approaches to form development. Both modules come from the same @angular/forms library package.

We've been reviewing the "Template-driven" approach which requires the FormsModule Here's how we imported it in the HeroFormTemplateModule.

template/hero-form-template.module.ts

import { NgModule } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { SharedModule } from '../shared/shared.module'; import { HeroFormTemplate1Component } from './hero-form-template1.component'; import { HeroFormTemplate2Component } from './hero-form-template2.component'; @NgModule({ imports: [ SharedModule, FormsModule ], declarations: [ HeroFormTemplate1Component, HeroFormTemplate2Component ], exports: [ HeroFormTemplate1Component, HeroFormTemplate2Component ] }) export class HeroFormTemplateModule { }

We haven'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

In the template-driven approach, you markup the template with form elements, validation attributes, and ng... directives from the Angular FormsModule. 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 andform... directives from the Angular ReactiveFormsModule. 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.

In return, you can

The third 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 FormsModule. The application module for the "Reactive Forms" feature in this sample looks like this:

app/reactive/hero-form-reactive.module.ts

import { NgModule } from '@angular/core'; import { ReactiveFormsModule } from '@angular/forms'; import { SharedModule } from '../shared/shared.module'; import { HeroFormReactiveComponent } from './hero-form-reactive.component'; @NgModule({ imports: [ SharedModule, ReactiveFormsModule ], declarations: [ HeroFormReactiveComponent ], exports: [ HeroFormReactiveComponent ] }) export class HeroFormReactiveModule { }

The "Reactive Forms" feature module and component are in the app/reactive folder. Let's focus on the HeroFormReactiveComponent there, starting with its template.

Component template

We begin by changing the <form> tag so that it binds the Angular formGroup directive in the template to the heroForm property in the component class. The heroForm is the control model that the component class builds and maintains.

<form [formGroup]="heroForm" *ngIf="active" (ngSubmit)="onSubmit()">

Then we 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:

<label for="name">Name</label> <input type="text" id="name" class="form-control" formControlName="name" required > <div *ngIf="formErrors.name" class="alert alert-danger"> {{ formErrors.name }} </div> <label for="name">Name</label> <input type="text" id="name" class="form-control" required minlength="4" maxlength="24" forbiddenName="bob" name="name" [(ngModel)]="hero.name" > <div *ngIf="formErrors.name" class="alert alert-danger"> {{ formErrors.name }} </div>

Key changes:

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 Validator.required function to the control model, as we'll do below.

The retreat from data binding is a principle of the reactive paradigm rather than a technical limitation.

Component class

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 we can no longer query for it. We create the Angular form control model explicitly with the help of the FormBuilder.

Here's the section of code devoted to that process, paired with the template-driven code it replaces:

heroForm: FormGroup; constructor(private fb: FormBuilder) { } ngOnInit(): void { this.buildForm(); } buildForm(): void { this.heroForm = this.fb.group({ 'name': [this.hero.name, [ Validators.required, Validators.minLength(4), Validators.maxLength(24), forbiddenNameValidator(/bob/i) ] ], 'alterEgo': [this.hero.alterEgo], 'power': [this.hero.power, Validators.required] }); this.heroForm.valueChanges .subscribe(data => this.onValueChanged(data)); this.onValueChanged(); // (re)set validation messages now } heroForm: NgForm; @ViewChild('heroForm') currentForm: NgForm; ngAfterViewChecked() { this.formChanged(); } formChanged() { if (this.currentForm === this.heroForm) { return; } this.heroForm = this.currentForm; if (this.heroForm) { this.heroForm.valueChanges .subscribe(data => this.onValueChanged(data)); } }

A real app would retrieve the hero asynchronously from a data service, a task best performed in the ngOnInit hook.

FormBuilder declaration

The 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 Validators class. Angular has stock validators that correspond to the standard HTML validation attributes.

The forbiddenNames validator on the "name" control is a custom validator, discussed in a separate section below.

Learn more about FormBuilder in a forthcoming chapter on reactive forms.

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:

  1. when the user submits the form
  2. when the user chooses to add a new hero

The onSubmit method simply replaces the hero object with the combined values of the form:

onSubmit() { this.submitted = true; this.hero = this.heroForm.value; }

This example is "lucky" in that the heroForm.value properties just happen to correspond exactly to the hero data object properties.

The addHero method discards pending changes and creates a brand new hero model object.

addHero() { this.hero = new Hero(42, '', ''); this.buildForm(); }

Then it calls buildForm again which replaces the previous heroForm control model with a new one. The <form> tag's [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.

import { Component, OnInit } from '@angular/core'; import { FormGroup, FormBuilder, Validators } from '@angular/forms'; import { Hero } from '../shared/hero'; import { forbiddenNameValidator } from '../shared/forbidden-name.directive'; @Component({ moduleId: module.id, selector: 'hero-form-reactive3', templateUrl: 'hero-form-reactive.component.html' }) export class HeroFormReactiveComponent implements OnInit { powers = ['Really Smart', 'Super Flexible', 'Weather Changer']; hero = new Hero(18, 'Dr. WhatIsHisName', this.powers[0], 'Dr. What'); submitted = false; onSubmit() { this.submitted = true; this.hero = this.heroForm.value; } addHero() { this.hero = new Hero(42, '', ''); this.buildForm(); this.active = false; setTimeout(() => this.active = true, 0); } heroForm: FormGroup; constructor(private fb: FormBuilder) { } ngOnInit(): void { this.buildForm(); } buildForm(): void { this.heroForm = this.fb.group({ 'name': [this.hero.name, [ Validators.required, Validators.minLength(4), Validators.maxLength(24), forbiddenNameValidator(/bob/i) ] ], 'alterEgo': [this.hero.alterEgo], 'power': [this.hero.power, Validators.required] }); this.heroForm.valueChanges .subscribe(data => this.onValueChanged(data)); this.onValueChanged(); // (re)set validation messages now } onValueChanged(data?: any) { if (!this.heroForm) { return; } const form = this.heroForm; for (const field in this.formErrors) { // clear previous error message (if any) this.formErrors[field] = ''; const control = form.get(field); if (control && control.dirty && !control.valid) { const messages = this.validationMessages[field]; for (const key in control.errors) { this.formErrors[field] += messages[key] + ' '; } } } } formErrors = { 'name': '', 'power': '' }; validationMessages = { 'name': { 'required': 'Name is required.', 'minlength': 'Name must be at least 4 characters long.', 'maxlength': 'Name cannot be more than 24 characters long.', 'forbiddenName': 'Someone named "Bob" cannot be a hero.' }, 'power': { 'required': 'Power is required.' } }; } import { Component, AfterViewChecked, ViewChild } from '@angular/core'; import { NgForm } from '@angular/forms'; import { Hero } from '../shared/hero'; @Component({ moduleId: module.id, selector: 'hero-form-template2', templateUrl: 'hero-form-template2.component.html' }) export class HeroFormTemplate2Component implements AfterViewChecked { powers = ['Really Smart', 'Super Flexible', 'Weather Changer']; hero = new Hero(18, 'Dr. WhatIsHisWayTooLongName', this.powers[0], 'Dr. What'); submitted = false; onSubmit() { this.submitted = true; } addHero() { this.hero = new Hero(42, '', ''); } heroForm: NgForm; @ViewChild('heroForm') currentForm: NgForm; ngAfterViewChecked() { this.formChanged(); } formChanged() { if (this.currentForm === this.heroForm) { return; } this.heroForm = this.currentForm; if (this.heroForm) { this.heroForm.valueChanges .subscribe(data => this.onValueChanged(data)); } } onValueChanged(data?: any) { if (!this.heroForm) { return; } const form = this.heroForm.form; for (const field in this.formErrors) { // clear previous error message (if any) this.formErrors[field] = ''; const control = form.get(field); if (control && control.dirty && !control.valid) { const messages = this.validationMessages[field]; for (const key in control.errors) { this.formErrors[field] += messages[key] + ' '; } } } } formErrors = { 'name': '', 'power': '' }; validationMessages = { 'name': { 'required': 'Name is required.', 'minlength': 'Name must be at least 4 characters long.', 'maxlength': 'Name cannot be more than 24 characters long.', 'forbiddenName': 'Someone named "Bob" cannot be a hero.' }, 'power': { 'required': 'Power is required.' } }; } import { Component } from '@angular/core'; import { Hero } from '../shared/hero'; @Component({ moduleId: module.id, selector: 'hero-form-template1', templateUrl: 'hero-form-template1.component.html' }) export class HeroFormTemplate1Component { powers = ['Really Smart', 'Super Flexible', 'Weather Changer']; hero = new Hero(18, 'Dr. WhatIsHisWayTooLongName', this.powers[0], 'Dr. What'); submitted = false; onSubmit() { this.submitted = true; } addHero() { this.hero = new Hero(42, '', ''); } }

Run the live example to see how the reactive form behaves and to compare all of the files in this cookbook sample.

Custom validation

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 app/shared folder and declared in the SharedModule.

Here's the forbiddenNamevalidator function itself:

shared/forbidden-name.directive.ts (forbiddenNameValidator)

/** A hero's name can't match the given regular expression */ export function forbiddenNameValidator(nameRe: RegExp): ValidatorFn { return (control: AbstractControl): {[key: string]: any} => { const name = control.value; const no = nameRe.test(name); return no ? {'forbiddenName': {name}} : null; }; }

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.

The 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 ('forbiddenName') and whose value is an arbitrary dictionary of values that we could insert into an error message ({name}).

Learn more about validator functions in a forthcoming chapter on custom form validation.

Custom validation directive

In the reactive forms component we added a configured forbiddenNamevalidator to the bottom of the 'name' control's validator function list.

reactive/hero-form-reactive.component.ts (name validators)

'name': [this.hero.name, [ Validators.required, Validators.minLength(4), Validators.maxLength(24), forbiddenNameValidator(/bob/i) ] ],

In the template-driven component template, we add the selector (forbiddenName) of a custom attribute directive to the name's input box and configured it to reject "bob".

template/hero-form-template2.component.html (name input)

<input type="text" id="name" class="form-control" required minlength="4" maxlength="24" forbiddenName="bob" name="name" [(ngModel)]="hero.name" >

The corresponding ForbiddenValidatorDirective is a wrapper around the forbiddenNamevalidator.

Angular forms recognizes the directive's role in the validation process because the directive registers itself with the NG_VALIDATORS provider, a provider with an extensible collection of validation directives.

shared/forbidden-name.directive.ts (providers)

providers: [{provide: NG_VALIDATORS, useExisting: ForbiddenValidatorDirective, multi: true}]

The rest of the directive is unremarkable and we present it here without further comment.

shared/forbidden-name.directive.ts (directive)

@Directive({ selector: '[forbiddenName]', providers: [{provide: NG_VALIDATORS, useExisting: ForbiddenValidatorDirective, multi: true}] }) export class ForbiddenValidatorDirective implements Validator, OnChanges { @Input() forbiddenName: string; private valFn = Validators.nullValidator; ngOnChanges(changes: SimpleChanges): void { const change = changes['forbiddenName']; if (change) { const val: string | RegExp = change.currentValue; const re = val instanceof RegExp ? val : new RegExp(val, 'i'); this.valFn = forbiddenNameValidator(re); } else { this.valFn = Validators.nullValidator; } } validate(control: AbstractControl): {[key: string]: any} { return this.valFn(control); } }

See the Attribute Directives chapter.

Testing Considerations

We 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.