Angular 12 References/ Forms
🍀 Angular References
Oleksa Novyk | GitHub

FormArray

A FormArray aggregates the values of each child FormControl into an array. It calculates its status by reducing the status values of its children. For example, if one of the controls in a FormArray is invalid, the entire array becomes invalid.

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

Interface, extends AbstractControl

at#

at(index: number): AbstractControl

Get the AbstractControl at the given index in the array.

push#

push(control: AbstractControl, options: {emitEvent?: boolean} = {}): void

Insert a new AbstractControl at the end of the array.

insert#

insert(index: number, control: AbstractControl, options: {emitEvent?: boolean} = {}): void

Insert a new AbstractControl at the given index in the array.

removeAt#

removeAt(index: number, options: {emitEvent?: boolean} = {}): void

Remove the control at the given index in the array.

setControl#

setControl(index: number, control: AbstractControl, options: {emitEvent?: boolean} = {}): void

Replace an existing control.

length#

get length(): number

Length of the control array.

setValue#

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

Sets the value of the FormArray. It accepts an array that matches the structure of the control.

This method performs strict checks, and throws 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.

Set the values for the controls in the form array

const arr = new FormArray([
new FormControl(),
new FormControl()
]);
console.log(arr.value);   // [null, null]

arr.setValue(['Nancy', 'Drew']);
console.log(arr.value);   // ['Nancy', 'Drew']

patchValue#

patchValue(value: any[], options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void

Patches the value of the FormArray. It accepts an array that matches the structure of the control, 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 array without throwing an error.

Patch the values for controls in a form array

const arr = new FormArray([
new FormControl(),
new FormControl()
]);
console.log(arr.value);   // [null, null]

arr.patchValue(['Nancy']);
console.log(arr.value);   // ['Nancy', null]

reset#

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

Resets the FormArray and all descendants are marked pristine and untouched, and the value of all descendants to null or null maps.

You reset to a specific form state by passing in an array of states that matches the structure of the control. The state is a standalone value or a form state object with both a value and a disabled status.

Reset the values in a form array

const arr = new FormArray([
new FormControl(),
new FormControl()
]);
arr.reset(['name', 'last name']);

console.log(arr.value);  // ['name', 'last name']

Reset the values in a form array and the disabled status for the first control

arr.reset([
{value: 'name', disabled: true},
'last'
]);

console.log(arr.value);  // ['last']
console.log(arr.at(0).status);  // 'DISABLED'

getRawValue#

getRawValue(): any[]

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

Reports all values regardless of disabled status. For enabled controls only, the value property is the best way to get the value of the array.

clear#

clear(options: {emitEvent?: boolean} = {}): void

Remove all controls in the FormArray.

Remove all elements from a FormArray

const arr = new FormArray([
new FormControl(),
new FormControl()
]);
console.log(arr.length);  // 2

arr.clear();
console.log(arr.length);  // 0

It's a simpler and more efficient alternative to removing all elements one by one:

const arr = new FormArray([
new FormControl(),
new FormControl()
]);

while (arr.length) {
arr.removeAt(0);
}