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

FormGroupDirective

npm Package @angular/forms
Module import { FormGroupDirective } from '@angular/forms';
Source forms/src/directives/reactive_directives/form_group_directive.ts

Binds an existing FormGroup to a DOM element.

Overview

      
      @Directive({
    selector: '[formGroup]',
    providers: [formDirectiveProvider],
    host: { '(submit)': 'onSubmit($event)', '(reset)': 'onReset()' },
    exportAs: 'ngForm'
})
class FormGroupDirective extends ControlContainer implements Form, OnChanges {
  get submitted: boolean
  directives: FormControlName[]
  form: FormGroup
  ngSubmit: new EventEmitter()
  ngOnChanges(changes: SimpleChanges): void
  get formDirective: Form
  get control: FormGroup
  get path: string[]
  addControl(dir: FormControlName): FormControl
  getControl(dir: FormControlName): FormControl
  removeControl(dir: FormControlName): void
  addFormGroup(dir: FormGroupName): void
  removeFormGroup(dir: FormGroupName): void
  getFormGroup(dir: FormGroupName): FormGroup
  addFormArray(dir: FormArrayName): void
  removeFormArray(dir: FormArrayName): void
  getFormArray(dir: FormArrayName): FormArray
  updateModel(dir: FormControlName, value: any): 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

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

npm package: @angular/forms

NgModule: ReactiveFormsModule

Selectors

      
      [formGroup]

Inputs

formGroup bound to FormGroupDirective.form

Outputs

ngSubmit bound to FormGroupDirective.ngSubmit

Exported as

Constructor

      
      constructor(_validators: any[], _asyncValidators: any[])

Members

      
      get submitted: boolean
    
      
      directives: FormControlName[]
    
      
      form: FormGroup
    
      
      ngSubmit: new EventEmitter()
    
      
      ngOnChanges(changes: SimpleChanges): void
    
      
      get formDirective: Form
    
      
      get control: FormGroup
    
      
      get path: string[]
    
      
      addControl(dir: FormControlName): FormControl
    
      
      getControl(dir: FormControlName): FormControl
    
      
      removeControl(dir: FormControlName): void
    
      
      addFormGroup(dir: FormGroupName): void
    
      
      removeFormGroup(dir: FormGroupName): void
    
      
      getFormGroup(dir: FormGroupName): FormGroup
    
      
      addFormArray(dir: FormArrayName): void
    
      
      removeFormArray(dir: FormArrayName): void
    
      
      getFormArray(dir: FormArrayName): FormArray
    
      
      updateModel(dir: FormControlName, value: any): void
    
      
      onSubmit($event: Event): boolean
    
      
      onReset(): void
    
      
      resetForm(value: any = undefined): void