This is the archived documentation for Angular v6. Please visit angular.io to see documentation for the current version of Angular.

NgForm

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

See more...

NgModule

Selectors

Properties

Property Description
submitted: boolean Read-only.
form: FormGroup
@Output()
ngSubmit: EventEmitter
@Input('ngFormOptions')
options: { updateOn?: FormHooks; }

Options for the NgForm instance. Accepts the following properties:

updateOn: Serves as the default updateOn value for all child NgModels below it (unless a child has explicitly set its own value for this in ngModelOptions). Potential values: 'change' | 'blur' | 'submit'

<form [ngFormOptions]="{updateOn: 'blur'}"> <input name="one" ngModel> <!-- this ngModel will update on blur --> </form>
      
      <form [ngFormOptions]="{updateOn: 'blur'}">
   <input name="one" ngModel>  <!-- this ngModel will update on blur -->
</form>
    
formDirective: Form Read-only.
control: FormGroup Read-only.
path: string[] Read-only.
controls: { [key: string]: AbstractControl; } Read-only.

Inherited from ControlContainer

Inherited from AbstractControlDirective

Template variable references

Identifier Usage
ngForm #myTemplateVar="ngForm"

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 } }
      
      
  1. import {Component} from '@angular/core';
  2. import {NgForm} from '@angular/forms';
  3.  
  4. @Component({
  5. selector: 'example-app',
  6. template: `
  7. <form #f="ngForm" (ngSubmit)="onSubmit(f)" novalidate>
  8. <input name="first" ngModel required #first="ngModel">
  9. <input name="last" ngModel>
  10. <button>Submit</button>
  11. </form>
  12. <p>First name value: {{ first.value }}</p>
  13. <p>First name valid: {{ first.valid }}</p>
  14. <p>Form value: {{ f.value | json }}</p>
  15. <p>Form valid: {{ f.valid }}</p>
  16. `,
  17. })
  18. export class SimpleFormComp {
  19. onSubmit(f: NgForm) {
  20. console.log(f.value); // { first: '', last: '' }
  21. console.log(f.valid); // false
  22. }
  23. }

npm package: @angular/forms

Methods

ngAfterViewInit()
      
      ngAfterViewInit()
    

Parameters

There are no parameters.

addControl(dir: NgModel): void
      
      addControl(dir: NgModel): void
    

Parameters

dir

Type: NgModel.

Returns

void

getControl(dir: NgModel): FormControl
      
      getControl(dir: NgModel): FormControl
    

Parameters

dir

Type: NgModel.

Returns

FormControl

removeControl(dir: NgModel): void
      
      removeControl(dir: NgModel): void
    

Parameters

dir

Type: NgModel.

Returns

void

addFormGroup(dir: NgModelGroup): void
      
      addFormGroup(dir: NgModelGroup): void
    

Parameters

dir

Type: NgModelGroup.

Returns

void

removeFormGroup(dir: NgModelGroup): void
      
      removeFormGroup(dir: NgModelGroup): void
    

Parameters

dir

Type: NgModelGroup.

Returns

void

getFormGroup(dir: NgModelGroup): FormGroup
      
      getFormGroup(dir: NgModelGroup): FormGroup
    

Parameters

dir

Type: NgModelGroup.

Returns

FormGroup

updateModel(dir: NgControl, value: any): void
      
      updateModel(dir: NgControl, value: any): void
    

Parameters

dir

Type: NgControl.

value

Type: any.

Returns

void

setValue(value: { [key: string]: any; }): void
      
      setValue(value: {
    [key: string]: any;
}): void
    

Parameters

value

Type: { [key: string]: any; }.

Returns

void

onSubmit($event: Event): boolean
      
      onSubmit($event: Event): boolean
    

Parameters

$event

Type: Event.

Returns

boolean

onReset(): void
      
      onReset(): void
    

Parameters

There are no parameters.

Returns

void

resetForm(value: any = undefined): void
      
      resetForm(value: any = undefined): void
    

Parameters

value

Type: any.

Optional. Default is undefined.

Returns

void

Inherited from AbstractControlDirective