Skip to content

Latest commit

 

History

History
202 lines (167 loc) · 5.79 KB

FormArray.md

File metadata and controls

202 lines (167 loc) · 5.79 KB

FormArray

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 Reactive Forms, 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('Jon', Validators.minLength(2)),
  new FormControl('Snow'),
]);

console.log(arr.value);   // ['Jon', 'Snow']
console.log(arr.status);  // 'VALID'

You can also include array-level validators and async validators. These come in handy when you want to perform validation that considers the value of more than one child control.

The two types of validators can be passed in separately as the second and third arg respectively, or together as part of an options object.

const arr = new FormArray([
  new FormControl('Jon'),
  new FormControl('Snow')
], {validators: myValidator, asyncValidators: myAsyncValidator});

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 array level, all child controls will default to 'blur', unless the child has explicitly specified a different updateOn value.

const c = new FormArray([
   new FormControl()
], {updateOn: 'blur'});

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.

Constructor

constructor(controls: AbstractControl[], validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null)

Members

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.

get length: number

Length of the control array.

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, 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 arr = new FormArray([
   new FormControl(),
   new FormControl()
]);
console.log(arr.value);   // [null, null]

arr.setValue(['Jon', 'Snow']);
console.log(arr.value);   // ['Jon', 'Snow']

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

Example

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

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

reset(value: any = [], options: {
    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.

Example

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.

handleSubmit():void

Submit action, can be used to tell the form that it has been submitted. Useful when updateOn property is submit.

Example

<form onSubmit={this.form.handleSubmit}/>



Note: This document is a derivative of "Form Array Document" by Google, under CC BY.