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

FormGroupDirective

Binds an existing FormGroup to a DOM element.

See more...

NgModule

Selectors

  • [formGroup]

Properties

Property Description
submitted: boolean Read-only.
directives: FormControlName[]
@Input('formGroup')
form: FormGroup
@Output()
ngSubmit: EventEmitter
formDirective: Form Read-only.
control: FormGroup Read-only.
path: string[] Read-only.

Inherited from ControlContainer

Inherited from AbstractControlDirective

Template variable references

Identifier Usage
ngForm #myTemplateVar="ngForm"

Description

This directive accepts an existing FormGroup instance. It will then use this FormGroup instance to match any child FormControl, FormGroup, and FormArray instances to child FormControlName, FormGroupName, and FormArrayName directives.

Set value: You can set the form's initial value when instantiating the FormGroup, or you can set it programmatically later using the FormGroup's setValue or patchValue methods.

Listen to value: If you want to listen to changes in the value of the form, you can subscribe to the FormGroup's valueChanges event. You can also listen to its statusChanges event to be notified when the validation status is re-calculated.

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

Example

In this example, we create form controls for first name and last name.

import {Component} from '@angular/core'; import {FormControl, FormGroup, Validators} from '@angular/forms'; @Component({ selector: 'example-app', template: ` <form [formGroup]="form" (ngSubmit)="onSubmit()"> <div *ngIf="first.invalid"> Name is too short. </div> <input formControlName="first" placeholder="First name"> <input formControlName="last" placeholder="Last name"> <button type="submit">Submit</button> </form> <button (click)="setValue()">Set preset value</button> `, }) export class SimpleFormGroup { form = new FormGroup({ first: new FormControl('Nancy', Validators.minLength(2)), last: new FormControl('Drew'), }); get first(): any { return this.form.get('first'); } onSubmit(): void { console.log(this.form.value); // {first: 'Nancy', last: 'Drew'} } setValue() { this.form.setValue({first: 'Carson', last: 'Drew'}); } }
      
      
  1. import {Component} from '@angular/core';
  2. import {FormControl, FormGroup, Validators} from '@angular/forms';
  3.  
  4. @Component({
  5. selector: 'example-app',
  6. template: `
  7. <form [formGroup]="form" (ngSubmit)="onSubmit()">
  8. <div *ngIf="first.invalid"> Name is too short. </div>
  9.  
  10. <input formControlName="first" placeholder="First name">
  11. <input formControlName="last" placeholder="Last name">
  12.  
  13. <button type="submit">Submit</button>
  14. </form>
  15. <button (click)="setValue()">Set preset value</button>
  16. `,
  17. })
  18. export class SimpleFormGroup {
  19. form = new FormGroup({
  20. first: new FormControl('Nancy', Validators.minLength(2)),
  21. last: new FormControl('Drew'),
  22. });
  23.  
  24. get first(): any { return this.form.get('first'); }
  25.  
  26. onSubmit(): void {
  27. console.log(this.form.value); // {first: 'Nancy', last: 'Drew'}
  28. }
  29.  
  30. setValue() { this.form.setValue({first: 'Carson', last: 'Drew'}); }
  31. }

Methods

ngOnChanges(changes: SimpleChanges): void
      
      ngOnChanges(changes: SimpleChanges): void
    

Parameters

changes

Type: SimpleChanges.

Returns

void

addControl(dir: FormControlName): FormControl
      
      addControl(dir: FormControlName): FormControl
    

Parameters

dir

Type: FormControlName.

Returns

FormControl

getControl(dir: FormControlName): FormControl
      
      getControl(dir: FormControlName): FormControl
    

Parameters

dir

Type: FormControlName.

Returns

FormControl

removeControl(dir: FormControlName): void
      
      removeControl(dir: FormControlName): void
    

Parameters

dir

Type: FormControlName.

Returns

void

addFormGroup(dir: FormGroupName): void
      
      addFormGroup(dir: FormGroupName): void
    

Parameters

dir

Type: FormGroupName.

Returns

void

removeFormGroup(dir: FormGroupName): void
      
      removeFormGroup(dir: FormGroupName): void
    

Parameters

dir

Type: FormGroupName.

Returns

void

getFormGroup(dir: FormGroupName): FormGroup
      
      getFormGroup(dir: FormGroupName): FormGroup
    

Parameters

dir

Type: FormGroupName.

Returns

FormGroup

addFormArray(dir: FormArrayName): void
      
      addFormArray(dir: FormArrayName): void
    

Parameters

dir

Type: FormArrayName.

Returns

void

removeFormArray(dir: FormArrayName): void
      
      removeFormArray(dir: FormArrayName): void
    

Parameters

dir

Type: FormArrayName.

Returns

void

getFormArray(dir: FormArrayName): FormArray
      
      getFormArray(dir: FormArrayName): FormArray
    

Parameters

dir

Type: FormArrayName.

Returns

FormArray

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

Parameters

dir

Type: FormControlName.

value

Type: 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