FormArrayName

directive

npm Package	@angular/forms
Module	import { FormArrayName } from '@angular/forms';
Source	forms/src/directives/reactive_directives/form_group_name.ts

Overview

@Directive({ selector: '[formArrayName]', providers: [formArrayNameProvider] })
class FormArrayName extends ControlContainer implements OnInit, OnDestroy {
  name: string
  ngOnInit(): void
  ngOnDestroy(): void
  get control: FormArray
  get formDirective: FormGroupDirective | null
  get path: string[]
  get validator: ValidatorFn | null
  get asyncValidator: AsyncValidatorFn | null
  // inherited from forms/ControlContainer
  name: string
  get formDirective: Form | null
  get path: string[] | null
  // inherited from forms/AbstractControlDirective
  get control: AbstractControl | null
  get value: any
  get valid: boolean | null
  get invalid: boolean | null
  get pending: boolean | null
  get disabled: boolean | null
  get enabled: boolean | null
  get errors: ValidationErrors | null
  get pristine: boolean | null
  get dirty: boolean | null
  get touched: boolean | null
  get status: string | null
  get untouched: boolean | null
  get statusChanges: Observable<any> | null
  get valueChanges: Observable<any> | null
  get path: string[] | null
  reset(value: any = undefined): void
  hasError(errorCode: string, path?: string[]): boolean
  getError(errorCode: string, path?: string[]): any
}

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; index as i">
          <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]

Inputs

Constructor

Members

name: string

ngOnInit(): void

ngOnDestroy(): void

get control: FormArray

get formDirective: FormGroupDirective | null

get path: string[]

get validator: ValidatorFn | null

get asyncValidator: AsyncValidatorFn | null