FormArray

A form array is a list of zero or more instances of the same form type.

For example, a list of your pets may look like the following:

class PetForm extends Form<{ name: Field<string>; animal: Field<string> }> {
  constructor(name?: string, animal?: string) {
    super({ name: Field.text(name), animal: Field.text(animal) });
  }
}

const pets = new FormArray<PetForm>();

constructor(rows)

Instantiates a new form array, optionally passing a list of rows to add as initial values.

const pets: FormArray<PetForm> = new FormArray([
  new PetForm("Buddy", "dog"),
  new PetForm("Zoe", "cat"),
]);

Properties

.rows

List of forms which this form array is currently comprised of.

const pets = new FormArray([new PetForm("Buddy")]);
console.log(pets.rows[0].fields.name.value); // prints "Buddy"

.errors

Observable list of validation errors of the form array. Shorthand for array.validation.errors.

.error

Observable validation error of the form array, if any. Shorthand for array.validation.errors[0].

Methods

.add(rows)

Adds one or more rows to the list. Returns the FormArray instance, useful for chaining.

const pets = new FormArray<PetForm>();
pets.add(new PetForm("Zoe"));
console.log(pets.rows[0].fields.name.value); // prints "Zoe"

.remove(index)

Removes a row from the list by its index. Returns the FormArray instance, useful for chaining.

const pets = new FormArray([new PetForm("Buddy"), new PetForm("Zoe")]);
pets.remove(1);
console.log(pets.rows.length); // prints 1
console.log(pets.rows[0].fields.name.value); // prints "Buddy"

.remove(row)

Removes a row from the list by its reference. Returns the FormArray instance, useful for chaining.

const cat = new PetForm("Zoe");
const pets = new FormArray([cat]);
pets.remove(cat);
console.log(pets.rows.length); // prints 0

.snapshot()

Recursively snapshots the current state of the form and returns it as a plain JavaScript array.

const characters = new FormArray([
  new Form({ name: Field.text("Homer"), show: Field.text("The Simpsons") }),
  new Form({ name: Field.text(""), show: Field.text() }),
]);

console.log(characters.snapshot());
// prints [{ name: "Homer", show: "The Simpsons" }, { name: "" }]

.reset()

Removes excess rows, adds missing rows, recursively resets each standing row, and removes the validation state.

const characters = new FormArray([new Form({ name: Field.text("Homer") })]);
characters.remove(0);
characters.add(new Form({ name: Field.text() }));

characters.reset();

console.log(characters.snapshot());
// prints [{ name: "Homer" }];

.validate()

Triggers validation using the form array's snapshot. All rows are validated as well.

Returns a promise for the finished validation state.

const pets = new FormArray([]);
const validation = await pets.validate();
if (validation.state === "valid") {
  console.log("The pets list and all its nested pet forms are valid");
}

.addValidators(...validators)

Adds one or more validators.
A validator is either a function, or an object with a validate function. It takes a snapshot of the form and throws an error, or returns a promise that rejects, if the value is invalid.

function isNotEmpty(rows: FormSnapshot<PetForm[]>) {
  if (rows.length === 0) {
    throw new Error("No pets listed");
  }
}

const pets = new FormArray([]);
await pets.addValidators(isNotEmpty).validate();
console.log(pets.error); // "No pets listed"