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

FormGroup

npm Package @angular/forms
Module import { FormGroup } from '@angular/forms';
Source forms/src/model.ts

Tracks the value and validity state of a group of FormControl instances.

A FormGroup aggregates the values of each child FormControl into one object, with each control name as the key. It calculates its status by reducing the statuses of its children. For example, if one of the controls in a group is invalid, the entire group becomes invalid.

FormGroup is one of the three fundamental building blocks used to define forms in Angular, along with FormControl and FormArray.

Overview

      
      class FormGroup extends AbstractControl {
  constructor(controls: {...}, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null)
  controls: {...}
  registerControl(name: string, control: AbstractControl): AbstractControl
  addControl(name: string, control: AbstractControl): void
  removeControl(name: string): void
  setControl(name: string, control: AbstractControl): void
  contains(controlName: string): boolean
  setValue(value: {...}, options: {...}): void
  patchValue(value: {...}, options: {...}): void
  reset(value: any = {}, options: {...}): void
  getRawValue(): any
  // inherited from forms/AbstractControl
  get value: any
  validator: ValidatorFn | null
  asyncValidator: AsyncValidatorFn | null
  get parent: FormGroup | FormArray
  get status: string
  get valid: boolean
  get invalid: boolean
  get pending: boolean
  get disabled: boolean
  get enabled: boolean
  get errors: ValidationErrors | null
  get pristine: boolean
  get dirty: boolean
  get touched: boolean
  get untouched: boolean
  get valueChanges: Observable<any>
  get statusChanges: Observable<any>
  get updateOn: FormHooks
  setValidators(newValidator: ValidatorFn | ValidatorFn[] | null): void
  setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[] | null): void
  clearValidators(): void
  clearAsyncValidators(): void
  markAsTouched(opts: {...}): void
  markAsUntouched(opts: {...}): void
  markAsDirty(opts: {...}): void
  markAsPristine(opts: {...}): void
  markAsPending(opts: {...}): void
  disable(opts: {...}): void
  enable(opts: {...}): void
  setParent(parent: FormGroup | FormArray): void
  setValue(value: any, options?: Object): void
  patchValue(value: any, options?: Object): void
  reset(value?: any, options?: Object): void
  updateValueAndValidity(opts: {...}): void
  setErrors(errors: ValidationErrors | null, opts: {...}): void
  get(path: Array<string | number> | string): AbstractControl | null
  getError(errorCode: string, path?: string[]): any
  hasError(errorCode: string, path?: string[]): boolean
  get root: AbstractControl
}

How To Use

When instantiating a FormGroup, pass in a collection of child controls as the first argument. The key for each child will be the name under which it is registered.

Example

      
      const form = new FormGroup({
  first: new FormControl('Nancy', Validators.minLength(2)),
  last: new FormControl('Drew'),
});

console.log(form.value);   // {first: 'Nancy', last; 'Drew'}
console.log(form.status);  // 'VALID'

You can also include group-level validators as the second arg, or group-level async validators as the third arg. These come in handy when you want to perform validation that considers the value of more than one child control.

Example

      
      const form = new FormGroup({
  password: new FormControl('', Validators.minLength(2)),
  passwordConfirm: new FormControl('', Validators.minLength(2)),
}, passwordMatchValidator);


function passwordMatchValidator(g: FormGroup) {
   return g.get('password').value === g.get('passwordConfirm').value
      ? null : {'mismatch': true};
}

Like FormControl instances, you can alternatively choose to pass in validators and async validators as part of an options object.

      
      const form = new FormGroup({
  password: new FormControl('')
  passwordConfirm: new FormControl('')
}, {validators: passwordMatchValidator, asyncValidators: otherValidator});

The options object can also be used to set a default value for each child control's updateOn property. If you set updateOn to 'blur' at the group level, all child controls will default to 'blur', unless the child has explicitly specified a different updateOn value.

      
      const c = new FormGroup({
   one: new FormControl()
}, {updateOn: 'blur'});
  • npm package: @angular/forms

Constructor

      
      constructor(controls: {
    [key: string]: AbstractControl;
}, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null)

Members

      
      controls: {
    [key: string]: AbstractControl;
}
    
      
      registerControl(name: string, control: AbstractControl): AbstractControl

Registers a control with the group's list of controls.

This method does not update the value or validity of the control, so for most cases you'll want to use addControl instead.

      
      addControl(name: string, control: AbstractControl): void

Add a control to this group.

      
      removeControl(name: string): void

Remove a control from this group.

      
      setControl(name: string, control: AbstractControl): void

Replace an existing control.

      
      contains(controlName: string): boolean

Check whether there is an enabled control with the given name in the group.

It will return false for disabled controls. If you'd like to check for existence in the group only, use get instead.

      
      setValue(value: {
    [key: string]: any;
}, options: {
    onlySelf?: boolean;
    emitEvent?: boolean;
} = {}): void

Sets the value of the FormGroup. It accepts an object that matches the structure of the group, with control names as keys.

This method performs strict checks, so it will throw an error if you try to set the value of a control that doesn't exist or if you exclude the value of a control.

Example

      
      const form = new FormGroup({
   first: new FormControl(),
   last: new FormControl()
});
console.log(form.value);   // {first: null, last: null}

form.setValue({first: 'Nancy', last: 'Drew'});
console.log(form.value);   // {first: 'Nancy', last: 'Drew'}
    
      
      patchValue(value: {
    [key: string]: any;
}, options: {
    onlySelf?: boolean;
    emitEvent?: boolean;
} = {}): void

Patches the value of the FormGroup. It accepts an object with control names as keys, and will do its best to match the values to the correct controls in the group.

It accepts both super-sets and sub-sets of the group without throwing an error.

Example

      
      const form = new FormGroup({
   first: new FormControl(),
   last: new FormControl()
});
console.log(form.value);   // {first: null, last: null}

form.patchValue({first: 'Nancy'});
console.log(form.value);   // {first: 'Nancy', last: null}
    
      
      reset(value: any = {}, options: {
    onlySelf?: boolean;
    emitEvent?: boolean;
} = {}): void

Resets the FormGroup. This means by default:

  • The group and all descendants are marked pristine
  • The group and all descendants are marked untouched
  • The value of all descendants will be null or null maps

You can also reset to a specific form state by passing in a map of states that matches the structure of your form, with control names as keys. The state can be a standalone value or a form state object with both a value and a disabled status.

Example

      
      this.form.reset({first: 'name', last: 'last name'});

console.log(this.form.value);  // {first: 'name', last: 'last name'}
  • OR -
      
      this.form.reset({
  first: {value: 'name', disabled: true},
  last: 'last'
});

console.log(this.form.value);  // {first: 'name', last: 'last name'}
console.log(this.form.get('first').status);  // 'DISABLED'
    
      
      getRawValue(): any

The aggregate value of the FormGroup, including any disabled controls.

If you'd like to include all values regardless of disabled status, use this method. Otherwise, the value property is the best way to get the value of the group.