{ "id": "api/forms/FormArray", "title": "FormArray", "contents": "\n\n
\n
\n
\n \n API > @angular/forms\n
\n
\n mode_edit\n code\n
\n
\n \n
\n

FormArraylink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

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

\n\n

See more...

\n
\n \n \n \n
\n\nclass FormArray extends AbstractControl {\n constructor(controls: AbstractControl[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])\n controls: AbstractControl[]\n length: number\n at(index: number): AbstractControl\n push(control: AbstractControl, options: { emitEvent?: boolean; } = {}): void\n insert(index: number, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void\n removeAt(index: number, options: { emitEvent?: boolean; } = {}): void\n setControl(index: number, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void\n setValue(value: any[], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n patchValue(value: any[], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n reset(value: any = [], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n getRawValue(): any[]\n clear(options: { emitEvent?: boolean; } = {}): void\n\n // inherited from forms/AbstractControl\n constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])\n value: any\n validator: ValidatorFn | null\n asyncValidator: AsyncValidatorFn | null\n parent: FormGroup | FormArray | null\n status: string\n valid: boolean\n invalid: boolean\n pending: boolean\n disabled: boolean\n enabled: boolean\n errors: ValidationErrors | null\n pristine: boolean\n dirty: boolean\n touched: boolean\n untouched: boolean\n valueChanges: Observable<any>\n statusChanges: Observable<any>\n updateOn: FormHooks\n root: AbstractControl\n setValidators(newValidator: ValidatorFn | ValidatorFn[]): void\n setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void\n clearValidators(): void\n clearAsyncValidators(): void\n markAsTouched(opts: { onlySelf?: boolean; } = {}): void\n markAllAsTouched(): void\n markAsUntouched(opts: { onlySelf?: boolean; } = {}): void\n markAsDirty(opts: { onlySelf?: boolean; } = {}): void\n markAsPristine(opts: { onlySelf?: boolean; } = {}): void\n markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n setParent(parent: FormGroup | FormArray): void\n abstract setValue(value: any, options?: Object): void\n abstract patchValue(value: any, options?: Object): void\n abstract reset(value?: any, options?: Object): void\n updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void\n get(path: string | (string | number)[]): AbstractControl | null\n getError(errorCode: string, path?: string | (string | number)[]): any\n hasError(errorCode: string, path?: string | (string | number)[]): boolean\n}\n\n\n \n \n\n
\n\n\n \n\n \n \n
\n

Descriptionlink

\n

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

\n

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

\n\n

Further information available in the Usage Notes...

\n
\n\n \n\n\n\n\n\n\n

Constructorlink

\n\n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n

Creates a new FormArray instance.

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

An array of child controls. Each child control is given an index\nwhere it is registered.

\n\n
\n \n validatorOrOpts\n ValidatorFn | AbstractControlOptions | ValidatorFn[]\n

A synchronous validator function, or an array of\nsuch functions, or an AbstractControlOptions object that contains validation functions\nand a validation trigger.

\n

Optional. Default is undefined.

\n\n
\n \n asyncValidator\n AsyncValidatorFn | AsyncValidatorFn[]\n

A single async validator or array of async validator functions

\n

Optional. Default is undefined.

\n\n
\n\n \n\n\n \n\n \n
\n
\n\n\n\n\n
\n

Propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n controls: AbstractControl[]\n \n Declared in Constructor\n \n

An array of child controls. Each child control is given an index\nwhere it is registered.

\n\n
\n \n length: number\n Read-Only\n \n

Length of the control array.

\n\n \n
\n
\n\n\n\n
\n

Methodslink

\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n at()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Get the AbstractControl at the given index in the array.

\n\n
\n
\n \n\n at(index: number): AbstractControl\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n index\n number\n

Index in the array to retrieve the control

\n\n
\n\n \n
Returns
\n

AbstractControl

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n push()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Insert a new AbstractControl at the end of the array.

\n\n
\n
\n \n\n push(control: AbstractControl, options: { emitEvent?: boolean; } = {}): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n control\n AbstractControl\n

Form control to be inserted

\n\n
\n \n options\n object\n

Specifies whether this FormArray instance should emit events after a new\ncontrol is added.

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control is\ninserted. When false, no events are emitted.\n
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n insert()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

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

Index in the array to insert the control

\n\n
\n \n control\n AbstractControl\n

Form control to be inserted

\n\n
\n \n options\n object\n

Specifies whether this FormArray instance should emit events after a new\ncontrol is inserted.

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control is\ninserted. When false, no events are emitted.\n
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n removeAt()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Remove the control at the given index in the array.

\n\n
\n
\n \n\n removeAt(index: number, options: { emitEvent?: boolean; } = {}): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n index\n number\n

Index in the array to remove the control

\n\n
\n \n options\n object\n

Specifies whether this FormArray instance should emit events after a\ncontrol is removed.

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control is\nremoved. When false, no events are emitted.\n
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n setControl()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Replace an existing control.

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

Index in the array to replace the control

\n\n
\n \n control\n AbstractControl\n

The AbstractControl control to replace the existing control

\n\n
\n \n options\n object\n

Specifies whether this FormArray instance should emit events after an\nexisting control is replaced with a new one.

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control is\nreplaced with a new one. When false, no events are emitted.\n
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n\n \n \n \n \n
\n
\n

\n setValue()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

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

Array of values for the controls

\n\n
\n \n options\n object\n

Configure options that determine how the control propagates changes and\nemits events after the value changes

\n
    \n
  • onlySelf: When true, each change only affects this control, and not its parent. Default\nis false.
    • \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges\nobservables emit events with the latest status and value when the control value is updated.\nWhen false, no events are emitted.\nThe configuration options are passed to the updateValueAndValidity method.\n
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n

This method performs strict checks, and throws an error if you try\nto set the value of a control that doesn't exist or if you exclude the\nvalue of a control.

\n\n
\n

Usage Noteslink

\n
Set the values for the controls in the form arraylink
\n\nconst arr = new FormArray([\n new FormControl(),\n new FormControl()\n]);\nconsole.log(arr.value); // [null, null]\n\narr.setValue(['Nancy', 'Drew']);\nconsole.log(arr.value); // ['Nancy', 'Drew']\n\n\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n\n \n \n \n \n
\n
\n

\n patchValue()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Patches the value of the FormArray. It accepts an array that matches the\nstructure of the control, and does its best to match the values to the correct\ncontrols in the group.

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

Array of latest values for the controls

\n\n
\n \n options\n object\n

Configure options that determine how the control propagates changes and\nemits events after the value changes

\n
    \n
  • onlySelf: When true, each change only affects this control, and not its parent. Default\nis false.
    • \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control value\nis updated. When false, no events are emitted. The configuration options are passed to\nthe updateValueAndValidity method.\n
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n

It accepts both super-sets and sub-sets of the array without throwing an error.

\n\n
\n

Usage Noteslink

\n
Patch the values for controls in a form arraylink
\n\nconst arr = new FormArray([\n new FormControl(),\n new FormControl()\n]);\nconsole.log(arr.value); // [null, null]\n\narr.patchValue(['Nancy']);\nconsole.log(arr.value); // ['Nancy', null]\n\n\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n\n \n \n \n \n
\n
\n

\n reset()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

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

Array of values for the controls

\n

Optional. Default is [].

\n\n
\n \n options\n object\n

Configure options that determine how the control propagates changes and\nemits events after the value changes

\n
    \n
  • onlySelf: When true, each change only affects this control, and not its parent. Default\nis false.
    • \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges\nobservables emit events with the latest status and value when the control is reset.\nWhen false, no events are emitted.\nThe configuration options are passed to the updateValueAndValidity method.\n
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n

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

\n\n
\n

Usage Noteslink

\n
Reset the values in a form arraylink
\n\nconst arr = new FormArray([\n new FormControl(),\n new FormControl()\n]);\narr.reset(['name', 'last name']);\n\nconsole.log(this.arr.value); // ['name', 'last name']\n\n
Reset the values in a form array and the disabled status for the first controllink
\n\nthis.arr.reset([\n {value: 'name', disabled: true},\n 'last'\n]);\n\nconsole.log(this.arr.value); // ['name', 'last name']\nconsole.log(this.arr.get(0).status); // 'DISABLED'\n\n\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n\n \n \n
\n
\n

\n getRawValue()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

\n\n
\n
\n \n\n getRawValue(): any[]\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

any[]

\n\n \n\n\n \n\n \n
\n
\n

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

\n\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n \n \n
\n
\n

\n clear()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Remove all controls in the FormArray.

\n\n
\n
\n \n\n clear(options: { emitEvent?: boolean; } = {}): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n options\n object\n

Specifies whether this FormArray instance should emit events after all\ncontrols are removed.

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when all controls\nin this FormArray instance are removed. When false, no events are emitted.
    • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n

Usage Noteslink

\n
Remove all elements from a FormArraylink
\n\nconst arr = new FormArray([\n new FormControl(),\n new FormControl()\n]);\nconsole.log(arr.length); // 2\n\narr.clear();\nconsole.log(arr.length); // 0\n\n

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

\n\nconst arr = new FormArray([\n new FormControl(),\n new FormControl()\n]);\n\nwhile (arr.length) {\n arr.removeAt(0);\n}\n\n\n
\n\n \n
\n\n\n\n \n
\n

Usage noteslink

\n

Create an array of form controlslink

\n\nconst arr = new FormArray([\n new FormControl('Nancy', Validators.minLength(2)),\n new FormControl('Drew'),\n]);\n\nconsole.log(arr.value); // ['Nancy', 'Drew']\nconsole.log(arr.status); // 'VALID'\n\n

Create a form array with array-level validatorslink

\n

You include array-level validators and async validators. These come in handy\nwhen you want to perform validation that considers the value of more than one child\ncontrol.

\n

The two types of validators are passed in separately as the second and third arg\nrespectively, or together as part of an options object.

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

Set the updateOn property for all controls in a form arraylink

\n

The options object is used to set a default value for each child\ncontrol's updateOn property. If you set updateOn to 'blur' at the\narray level, all child controls default to 'blur', unless the child\nhas explicitly specified a different updateOn value.

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

Adding or removing controls from a form arraylink

\n

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

\n\n
\n\n\n\n
\n
\n\n\n" }