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'}); }
  }

NgModule

• ReactiveFormsModule

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

• name: string
• formDirective: Form | null
• path: string[] | null

Inherited from AbstractControlDirective

• abstract control: AbstractControl | null
• value: any
• valid: boolean | null
• invalid: boolean | null
• pending: boolean | null
• disabled: boolean | null
• enabled: boolean | null
• errors: ValidationErrors | null
• pristine: boolean | null
• dirty: boolean | null
• touched: boolean | null
• status: string | null
• untouched: boolean | null
• statusChanges: Observable<any> | null
• valueChanges: Observable<any> | null
• path: string[] | null

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

ngOnChanges()
A lifecycle method called when the directive's inputs change. For internal use only.
ngOnChanges(changes: SimpleChanges): void Parameters changes SimpleChanges A object of key/value pairs for the set of changed inputs. Returns void

addControl()
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 Parameters dir FormControlName The FormControlName directive instance. Returns FormControl

getControl()
Retrieves the FormControl instance from the provided FormControlName directive
getControl(dir: FormControlName): FormControl Parameters dir FormControlName The FormControlName directive instance. Returns FormControl

removeControl()
Removes the FormControlName instance from the internal list of directives
removeControl(dir: FormControlName): void Parameters dir FormControlName The FormControlName directive instance. Returns void

addFormGroup()
Adds a new FormGroupName directive instance to the form.
addFormGroup(dir: FormGroupName): void Parameters dir FormGroupName The FormGroupName directive instance. Returns void

removeFormGroup()
No-op method to remove the form group.
removeFormGroup(dir: FormGroupName): void Parameters dir FormGroupName The FormGroupName directive instance. Returns void

getFormGroup()
Retrieves the FormGroup for a provided FormGroupName directive instance
getFormGroup(dir: FormGroupName): FormGroup Parameters dir FormGroupName The FormGroupName directive instance. Returns FormGroup

addFormArray()
Adds a new FormArrayName directive instance to the form.
addFormArray(dir: FormArrayName): void Parameters dir FormArrayName The FormArrayName directive instance. Returns void

removeFormArray()
No-op method to remove the form array.
removeFormArray(dir: FormArrayName): void Parameters dir FormArrayName The FormArrayName directive instance. Returns void

getFormArray()
Retrieves the FormArray for a provided FormArrayName directive instance.
getFormArray(dir: FormArrayName): FormArray Parameters dir FormArrayName The FormArrayName directive instance. Returns FormArray

updateModel()
Sets the new value for the provided FormControlName directive.
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

onSubmit()
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 Parameters $event Event The "submit" event object Returns boolean

onReset()
Method called when the "reset" event is triggered on the form.
onReset(): void Parameters There are no parameters. Returns void

resetForm()
Resets the form to an initial value and resets its submitted status.
resetForm(value: any = undefined): void Parameters value any The new value for the form. Optional. Default is undefined. Returns void

Inherited from AbstractControlDirective

• reset(value: any = undefined): void
• hasError(errorCode: string, path?: string | (string | number)[]): boolean
• getError(errorCode: string, path?: string | (string | number)[]): any