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

See more...

NgModule

• FormsModule

Selectors

• form:not([ngNoForm]):not([formGroup])
• ngForm
• [ngForm]

Properties

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

Inherited from ControlContainer

• name: string
• formDirective: Form | null
• path: string[] | null

Inherited from AbstractControlDirective

• abstract control: AbstractControl | null
• value: any
• valid: boolean | null
• invalid: boolean | null
• pending: boolean | null
• disabled: boolean | null
• enabled: boolean | null
• errors: ValidationErrors | null
• pristine: boolean | null
• dirty: boolean | null
• touched: boolean | null
• status: string | null
• untouched: boolean | null
• statusChanges: Observable<any> | null
• valueChanges: Observable<any> | null
• path: string[] | null

Template variable references

Description

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 can 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 will give 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, you'll want to use NgModel with a name attribute. You can also use NgModelGroup if you'd like to create sub-groups within the form.

You can listen to the directive's ngSubmit event to be notified when the user has triggered a form submission. The ngSubmit event will be emitted with the original form submission event.

In template driven forms, all <form> tags are automatically tagged as NgForm. If you want to import the FormsModule but skip its usage in some forms, for example, to use native HTML5 validation, you can add 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.

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

@Component({
  selector: 'example-app',
  template: `
    <form #f="ngForm" (ngSubmit)="onSubmit(f)" novalidate>
      <input name="first" ngModel required #first="ngModel">
      <input name="last" ngModel>
      <button>Submit</button>
    </form>
    
    <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
  }
}

npm package: @angular/forms

Methods

Inherited from AbstractControlDirective

• reset(value: any = undefined): void
• hasError(errorCode: string, path?: string[]): boolean
• getError(errorCode: string, path?: string[]): any