Help Angular by taking a 1 minute survey!Go to surveyHome

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.

Returns whether the form submission has been triggered.

form: FormGroup

The FormGroup instance created for this form.

@Output()
ngSubmit: EventEmitter

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

formDirective: Form Read-only.

The directive instance.

control: FormGroup Read-only.

The internal FormGroup instance.

path: string[] Read-only.

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.

controls: { [key: string]: AbstractControl; } Read-only.

Returns a map of the controls in this group.

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

Migrating from deprecated ngForm selector

Support for using ngForm element selector has been deprecated in Angular v6 and will be removed in Angular v9.

This has been deprecated to keep selectors consistent with other core Angular selectors, as element selectors are typically written in kebab-case.

Now deprecated:

<ngForm #myForm="ngForm">
      
      <ngForm #myForm="ngForm">
    

After:

<ng-form #myForm="ngForm">
      
      <ng-form #myForm="ngForm">
    

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'; @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. }

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

Methods

Lifecycle method called after the view is initialized. For internal use only.

ngAfterViewInit()
      
      ngAfterViewInit()
    
Parameters

There are no parameters.

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.

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

The NgModel directive instance.

Returns

void

Retrieves the FormControl instance from the provided NgModel directive.

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

The NgModel directive instance.

Returns

FormControl

Removes the NgModel instance from the internal list of directives

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

The NgModel directive instance.

Returns

void

Adds a new NgModelGroup directive instance to the form.

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

The NgModelGroup directive instance.

Returns

void

Removes the NgModelGroup directive instance from the form.

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

The NgModelGroup directive instance.

Returns

void

Retrieves the FormGroup for a provided NgModelGroup directive instance

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

The NgModelGroup directive instance.

Returns

FormGroup

Sets the new value for the provided NgControl directive.

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

The NgControl directive instance.

value any

The new value for the directive's control.

Returns

void

Sets the value for this FormGroup.

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

The new value

Returns

void

Method called when the "submit" event is triggered on the form. Triggers the ngSubmit emitter to emit the "submit" event as its payload.

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

The "submit" event object

Returns

boolean

Method called when the "reset" event is triggered on the form.

onReset(): void
      
      onReset(): void
    
Parameters

There are no parameters.

Returns

void

Resets the form to an initial value and resets its submitted status.

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

The new value for the form.

Optional. Default is undefined.

Returns

void

Inherited from AbstractControlDirective