W3cubDocs

/Angular 4 TypeScript

NgForm

Stable Directive

What it does

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

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.

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

Class Overview

class NgForm extends ControlContainer implements Form {
  constructor(validators: any[], asyncValidators: any[])
  
  
  form : FormGroup
  ngSubmit : EventEmitter
  submitted : boolean
  formDirective : Form
  control : FormGroup
  path : string[]
  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) : void
}

Selectors

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

ngForm

[ngForm]

Outputs

ngSubmit bound to NgForm.ngSubmit

Exported as

ngForm

Class Description

Constructor

constructor(validators: any[], asyncValidators: any[])

Class Details

form : FormGroup
ngSubmit : EventEmitter
submitted : boolean
formDirective : Form
control : FormGroup
path : string[]
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) : void

exported from forms/index, defined in forms/src/directives/ng_form.ts

© 2010–2017 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://angular.io/docs/ts/latest/api/forms/index/NgForm-directive.html