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

See more...

class FormArray<TControl extends AbstractControl<any> = any> extends AbstractControl<ɵTypedOrUntyped<TControl, ɵFormArrayValue<TControl>, any>, ɵTypedOrUntyped<TControl, ɵFormArrayRawValue<TControl>, any>> {
  constructor(controls: TControl[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])
  controls: ɵTypedOrUntyped<TControl, Array<TControl>, Array<AbstractControl<any>>>
  length: number
  at(index: number): ɵTypedOrUntyped<TControl, TControl, AbstractControl<any>>
  push(control: TControl, options: { emitEvent?: boolean; } = {}): void
  insert(index: number, control: TControl, options: { emitEvent?: boolean; } = {}): void
  removeAt(index: number, options: { emitEvent?: boolean; } = {}): void
  setControl(index: number, control: TControl, options: { emitEvent?: boolean; } = {}): void
  setValue(value: ɵIsAny<TControl, any[], ɵRawValue<TControl>[]>, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  patchValue(value: ɵIsAny<TControl, any[], ɵValue<TControl>[]>, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  reset(value: ɵIsAny<TControl, any, ɵIsAny<TControl, any[], ɵValue<TControl>[]>> = [], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  getRawValue(): ɵFormArrayRawValue<TControl>
  clear(options: { emitEvent?: boolean; } = {}): void

  // inherited from forms/AbstractControl
  constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])
  value: TValue
  validator: ValidatorFn | null
  asyncValidator: AsyncValidatorFn | null
  parent: FormGroup | FormArray | null
  status: FormControlStatus
  valid: boolean
  invalid: boolean
  pending: boolean
  disabled: boolean
  enabled: boolean
  errors: ValidationErrors | null
  pristine: boolean
  dirty: boolean
  touched: boolean
  untouched: boolean
  valueChanges: Observable<TValue>
  statusChanges: Observable<FormControlStatus>
  updateOn: FormHooks
  root: AbstractControl
  setValidators(validators: ValidatorFn | ValidatorFn[]): void
  setAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  addValidators(validators: ValidatorFn | ValidatorFn[]): void
  addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  removeValidators(validators: ValidatorFn | ValidatorFn[]): void
  removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  hasValidator(validator: ValidatorFn): boolean
  hasAsyncValidator(validator: AsyncValidatorFn): boolean
  clearValidators(): void
  clearAsyncValidators(): void
  markAsTouched(opts: { onlySelf?: boolean; } = {}): void
  markAllAsTouched(): void
  markAsUntouched(opts: { onlySelf?: boolean; } = {}): void
  markAsDirty(opts: { onlySelf?: boolean; } = {}): void
  markAsPristine(opts: { onlySelf?: boolean; } = {}): void
  markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setParent(parent: FormGroup<any> | FormArray<any>): void
  abstract setValue(value: TRawValue, options?: Object): void
  abstract patchValue(value: TValue, options?: Object): void
  abstract reset(value?: TValue, options?: Object): void
  getRawValue(): any
  updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void
  get<P extends string | ((string | number)[])>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | null
  getError(errorCode: string, path?: string | (string | number)[]): any
  hasError(errorCode: string, path?: string | (string | number)[]): boolean
}

Description

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 accepts one generic argument, which is the type of the controls inside. If you need a heterogenous array, use UntypedFormArray.

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

Further information is available in the Usage Notes...

Constructor

Properties

Methods

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

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

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

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

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

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

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

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

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

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

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

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

Usage notes

Create an array of form controls

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

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

Create a form array with array-level validators

You 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 are passed in separately as the second and third arg respectively, or together as part of an options object.

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

Set the updateOn property for all controls in a form array

The options object is 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 default to 'blur', unless the child has explicitly specified a different updateOn value.

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

Adding or removing controls from a form array

To change the controls in the array, use the push, insert, removeAt or clear 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 result in strange and unexpected behavior such as broken change detection.