FormGroup

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 status values 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.

When instantiating a FormGroup, pass in a collection of child controls as the first argument. The key for each child registers the name for the control.

Interface, extends AbstractControl

registerControl#

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. Use {@link FormGroup#addControl addControl} instead.

addControl#

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

Add a control to this group.

This method also updates the value and validity of the control.

removeControl#

removeControl(name: string): void

Remove a control from this group.

setControl#

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

Replace an existing control.

contains#

contains(controlName: string): boolean

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

Reports false for disabled controls. If you'd like to check for existence in the group only, use {@link AbstractControl#get get} instead.

Returns false for disabled controls, true otherwise.

setValue#

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.

Set the complete value for the form group

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#

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

Patch the value for a form group

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#

reset(value: any = {}, options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void

Resets the FormGroup, marks all descendants are marked pristine and untouched, and the value of all descendants to null.

You 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 is a standalone value or a form state object with both a value and a disabled status.

Reset the form group values

const form = new FormGroup({
   first: new FormControl('first name'),
   last: new FormControl('last name')
});

console.log(form.value);  // {first: 'first name', last: 'last name'}

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

console.log(form.value);  // {first: 'name', last: 'last name'}

Reset the form group values and disabled status

const form = new FormGroup({
   first: new FormControl('first name'),
   last: new FormControl('last name')
});

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#

getRawValue(): any

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

Retrieves all values regardless of disabled status. The value property is the best way to get the value of the group, because it excludes disabled controls in the FormGroup.