FormArray

Stable Class

What it does

Tracks the value and validity state of an array of FormControl, FormGroup or FormArray instances.

A FormArray aggregates the values of each child FormControl into an array. It calculates its status by reducing the statuses 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.

How to use

When instantiating a FormArray, pass in an array of child controls as the first argument.

Example

const arr = new FormArray([
  new FormControl('Nancy', Validators.minLength(2)),
  new FormControl('Drew'),
]);

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

You can also include array-level validators as the second arg, or array-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.

Adding or removing controls

To change the controls in the array, use the push, insert, or removeAt methods in FormArray itself. These methods ensure the controls are properly tracked in the form's hierarchy. Do not modify the array of AbstractControls used to instantiate the FormArray directly, as that will result in strange and unexpected behavior such as broken change detection.

• npm package: @angular/forms

Class Overview

class FormArray extends AbstractControl {
  constructor(controls: AbstractControl[], validator?: ValidatorFn, asyncValidator?: AsyncValidatorFn)
  
  
  controls : AbstractControl[]
  at(index: number) : AbstractControl
  push(control: AbstractControl) : void
  insert(index: number, control: AbstractControl) : void
  removeAt(index: number) : void
  setControl(index: number, control: AbstractControl) : void
  length : number
  setValue(value: any[], {onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
  patchValue(value: any[], {onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
  reset(value?: any, {onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
  getRawValue() : any[]
}

Class Description

Constructor

constructor(controls: AbstractControl[], validator?: ValidatorFn, asyncValidator?: AsyncValidatorFn)

Class Details

controls : AbstractControl[]

at(index: number) : AbstractControl

Get the AbstractControl at the given index in the array.

push(control: AbstractControl) : void

Insert a new AbstractControl at the end of the array.

insert(index: number, control: AbstractControl) : void

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

removeAt(index: number) : void

Remove the control at the given index in the array.

setControl(index: number, control: AbstractControl) : void

Replace an existing control.

length : number

Length of the control array.

setValue(value: any[], {onlySelf, emitEvent}?: {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, 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.

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(value: any[], {onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void

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

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

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

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

Resets the FormArray. This means by default:

• The array and all descendants are marked pristine
• The array 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 an array of states that matches the structure of the control. The state can be a standalone value or a form state object with both a value and a disabled status.

this.arr.reset(['name', 'last name']);

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

• OR -

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

console.log(this.arr.value);  // ['name', 'last name']
console.log(this.arr.get(0).status);  // 'DISABLED'

getRawValue() : any[]

The aggregate value of the array, 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 array.

exported from @angular/forms/index, defined in @angular/forms/src/model.ts