NgForm

directive

Overview

@Directive({
    selector: 'form:not([ngNoForm]):not([formGroup]),ngForm,[ngForm]',
    providers: [formDirectiveProvider],
    host: { '(submit)': 'onSubmit($event)', '(reset)': 'onReset()' },
    outputs: ['ngSubmit'],
    exportAs: 'ngForm'
})
class NgForm extends ControlContainer implements Form, AfterViewInit {
  get submitted: boolean
  form: FormGroup
  ngSubmit: new EventEmitter()
  options: {...}
  ngAfterViewInit()
  get formDirective: Form
  get control: FormGroup
  get path: string[]
  get controls: {...}
  addControl(dir: NgModel): void
  getControl(dir: NgModel): FormControl
  removeControl(dir: NgModel): void
  addFormGroup(dir: NgModelGroup): void
  removeFormGroup(dir: NgModelGroup): void
  getFormGroup(dir: NgModelGroup): FormGroup
  updateModel(dir: NgControl, value: any): void
  setValue(value: {...}): void
  onSubmit($event: Event): boolean
  onReset(): void
  resetForm(value: any = undefined): void
  // inherited from forms/ControlContainer
  name: string
  get formDirective: Form | null
  get path: string[] | null
  // inherited from forms/AbstractControlDirective
  get control: AbstractControl | null
  get value: any
  get valid: boolean | null
  get invalid: boolean | null
  get pending: boolean | null
  get disabled: boolean | null
  get enabled: boolean | null
  get errors: ValidationErrors | null
  get pristine: boolean | null
  get dirty: boolean | null
  get touched: boolean | null
  get status: string | null
  get untouched: boolean | null
  get statusChanges: Observable<any> | null
  get valueChanges: Observable<any> | null
  get path: string[] | null
  reset(value: any = undefined): void
  hasError(errorCode: string, path?: string[]): boolean
  getError(errorCode: string, path?: string[]): any
}

How To Use

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

• NgModule: FormsModule

Selectors

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

Inputs

Outputs

Exported as

Constructor

Members

get submitted: boolean

form: FormGroup

ngSubmit: new EventEmitter()

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>

ngAfterViewInit()

get formDirective: Form

get control: FormGroup

get path: string[]

get controls: { [key: string]: AbstractControl; }

addControl(dir: NgModel): void

getControl(dir: NgModel): FormControl

removeControl(dir: NgModel): void

addFormGroup(dir: NgModelGroup): void

removeFormGroup(dir: NgModelGroup): void

getFormGroup(dir: NgModelGroup): FormGroup

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

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

onSubmit($event: Event): boolean

onReset(): void

resetForm(value: any = undefined): void