What it does

Syncs a nested FormArray to a DOM element.

How to use

This directive is designed to be used with a parent FormGroupDirective (selector: [formGroup]).

It accepts the string name of the nested FormArray you want to link, and will look for a FormArray registered with that name in the parent FormGroup instance you passed into FormGroupDirective.

Nested form arrays can come in handy when you have a group of form controls but you're not sure how many there will be. Form arrays allow you to create new form controls dynamically.

Access the array: You can access the associated FormArray using the get method on the parent FormGroup. Ex: this.form.get('cities').

Get the value: the value property is always synced and available on the FormArray. See a full list of available properties in AbstractControl.

Set the value: You can set an initial value for each child control when instantiating the FormArray, or you can set the value programmatically later using the FormArray's setValue or patchValue methods.

Listen to value: If you want to listen to changes in the value of the array, you can subscribe to the FormArray's valueChanges event. You can also listen to its statusChanges event to be notified when the validation status is re-calculated.

Add new controls: You can add new controls to the FormArray dynamically by calling its push method. Ex: this.form.get('cities').push(new FormControl());

Example

import {Component} from '@angular/core';
import {FormArray, FormControl, FormGroup} from '@angular/forms';

@Component({
  selector: 'example-app',
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      <div formArrayName="cities">
        <div *ngFor="let city of cities.controls; let i=index">
          <input [formControlName]="i" placeholder="City">
        </div>
      </div>
      <button>Submit</button>
    </form>

    <button (click)="addCity()">Add City</button>
    <button (click)="setPreset()">Set preset</button>
  `,
})
export class NestedFormArray {
  form = new FormGroup({
    cities: new FormArray([
      new FormControl('SF'),
      new FormControl('NY'),
    ]),
  });

  get cities(): FormArray { return this.form.get('cities') as FormArray; }

  addCity() { this.cities.push(new FormControl()); }

  onSubmit() {
    console.log(this.cities.value);  // ['SF', 'NY']
    console.log(this.form.value);    // { cities: ['SF', 'NY'] }
  }

  setPreset() { this.cities.patchValue(['LA', 'MTV']); }
}

• npm package: @angular/forms

• NgModule: ReactiveFormsModule

Selectors

[formArrayName]

Class Description

Constructor

constructor(parent: ControlContainer, validators: any[], asyncValidators: any[])