Angular 10 References/ Forms

[ngForm] directive

Creates a top-level FormGroup instance and binds it to a form to track aggregate form value and validation status.

As soon as you import the FormsModule, this directive becomes active by default on all <form> tags. You don't need to add a special selector.

You optionally export the directive into a local template variable using ngForm as the key (ex: #myForm="ngForm"). This is optional, but useful. Many properties from the underlying FormGroup instance are duplicated on the directive itself, so a reference to it gives you access to the aggregate value and validity status of the form, as well as user interaction properties like dirty and touched.

To register child controls with the form, use NgModel with a name attribute. You may use NgModelGroup to create sub-groups within the form.

If necessary, listen to the directive's ngSubmit event to be notified when the user has triggered a form submission. The ngSubmit event emits the original form submission event.

In template driven forms, all <form> tags are automatically tagged as NgForm. To import the FormsModule but skip its usage in some forms, for example, to use native HTML5 validation, add the ngNoForm and the <form> tags won't create an NgForm directive. In reactive forms, using ngNoForm is unnecessary because the <form> tags are inert. In that case, you would refrain from using the formGroup directive.

Listening for form submission

The following example shows how to capture the form values from the "ngSubmit" event.

import {Component} from '@angular/core';
import {NgForm} from '@angular/forms';

  selector: 'example-app',
  template: `
    <form #f="ngForm" (ngSubmit)="onSubmit(f)" novalidate>
      <input name="first" ngModel required #first="ngModel">
      <input name="last" ngModel>

    <p>First name value: {{ first.value }}</p>
    <p>First name valid: {{ first.valid }}</p>
    <p>Form value: {{ f.value | json }}</p>
    <p>Form valid: {{ f.valid }}</p>
export class SimpleFormComp {
  onSubmit(f: NgForm) {
    console.log(f.value);  // { first: '', last: '' }
    console.log(f.valid);  // false

Setting the update options

The following example shows you how to change the updateOn option from its default using ngFormOptions.

<form [ngFormOptions]="{updateOn: 'blur'}">
   <input name="one" ngModel>  <!-- this ngModel will update on blur -->

Interface, extends ControlContainer


submitted: boolean
Returns whether the form submission has been triggered.


form: FormGroup
The `FormGroup` instance created for this form.


Event emitter for the "ngSubmit" event


@Input('ngFormOptions') options: {updateOn?: FormHooks}
Tracks options for the `NgForm` instance. **updateOn**: Sets the default `updateOn` value for all child `NgModels` below it unless explicitly set by a child `NgModel` using `ngModelOptions`). Defaults to 'change'. Possible values: `'change'` | `'blur'` | `'submit'`.


get formDirective(): Form
The directive instance.


get control(): FormGroup
The internal `FormGroup` instance.


get path(): string[]
Returns an array representing the path to this group. Because this directive always lives at the top level of a form, it is always an empty array.


get controls(): {[key: string]: AbstractControl}
Returns a map of the controls in this group.


addControl(dir: NgModel): void
Method that sets up the control directive in this group, re-calculates its value and validity, and adds the instance to the internal list of directives.


getControl(dir: NgModel): FormControl
Retrieves the `FormControl` instance from the provided `NgModel` directive.


removeControl(dir: NgModel): void
Removes the `NgModel` instance from the internal list of directives


addFormGroup(dir: NgModelGroup): void
Adds a new `NgModelGroup` directive instance to the form.


removeFormGroup(dir: NgModelGroup): void
Removes the `NgModelGroup` directive instance from the form.


getFormGroup(dir: NgModelGroup): FormGroup
Retrieves the `FormGroup` for a provided `NgModelGroup` directive instance


updateModel(dir: NgControl, value: any): void
Sets the new value for the provided `NgControl` directive.


setValue(value: {[key: string]: any}): void
Sets the value for this `FormGroup`.


onSubmit($event: Event): boolean
Method called when the "submit" event is triggered on the form. Triggers the `ngSubmit` emitter to emit the "submit" event as its payload.


onReset(): void
Method called when the "reset" event is triggered on the form.


resetForm(value: any = undefined): void
Resets the form to an initial value and resets its submitted status.