What it does
Tracks the value and validity state of an array of FormControl 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 {
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}?: {onlySelf?: boolean}) : void
patchValue(value: any[], {onlySelf}?: {onlySelf?: boolean}) : void
reset(value?: any, {onlySelf}?: {onlySelf?: 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}?: {onlySelf?: 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}?: {onlySelf?: 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}?: {onlySelf?: 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
Please login to continue.