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

FormGroupDirective

Binds an existing FormGroup to a DOM element.

See more...

See also

  • Reactive Forms Guide

  • AbstractControl

    Register Form Group

    The following example registers a FormGroup with first name and last name controls, and listens for the ngSubmit event when the button is clicked.

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

NgModule

Selectors

  • [formGroup]

Properties

Property Description
submitted: boolean Read-only.

Reports whether the form submission has been triggered.

directives: FormControlName[]

Tracks the list of added FormControlName instances

@Input('formGroup')
form: FormGroup

Tracks the FormGroup bound to this directive.

@Output()
ngSubmit: EventEmitter

Emits an event when the form submission has been triggered.

formDirective: Form Read-only.

Returns this directive's instance.

control: FormGroup Read-only.

Returns the FormGroup bound to this directive.

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 always an empty array.

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.

Methods

A lifecycle method called when the directive's inputs change. For internal use only.

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

A object of key/value pairs for the set of changed inputs.

Returns

void

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: FormControlName): FormControl
      
      addControl(dir: FormControlName): FormControl
    
Parameters
dir FormControlName

The FormControlName directive instance.

Returns

FormControl

Retrieves the FormControl instance from the provided FormControlName directive

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

The FormControlName directive instance.

Returns

FormControl

Removes the FormControlName instance from the internal list of directives

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

The FormControlName directive instance.

Returns

void

Adds a new FormGroupName directive instance to the form.

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

The FormGroupName directive instance.

Returns

void

No-op method to remove the form group.

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

The FormGroupName directive instance.

Returns

void

Retrieves the FormGroup for a provided FormGroupName directive instance

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

The FormGroupName directive instance.

Returns

FormGroup

Adds a new FormArrayName directive instance to the form.

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

The FormArrayName directive instance.

Returns

void

No-op method to remove the form array.

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

The FormArrayName directive instance.

Returns

void

Retrieves the FormArray for a provided FormArrayName directive instance.

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

The FormArrayName directive instance.

Returns

FormArray

Sets the new value for the provided FormControlName directive.

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

The FormControlName directive instance.

value any

The new value for the directive's control.

Returns

void

Method called with 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