From 2ecbc4e6437e8748d6e498f5d3ef371b8696aa22 Mon Sep 17 00:00:00 2001
From: Matthieu Riegler <kyro38@gmail.com>
Date: Fri, 10 Oct 2025 15:18:43 +0200
Subject: [PATCH] docs: add a callout that adding/removing to formArray doesn't
 not mark dirty (#64337)

fixes #36788

PR Close #64337
---
 packages/forms/src/model/form_array.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/forms/src/model/form_array.ts b/packages/forms/src/model/form_array.ts
index 1e5a07bc76d..22649bbb98d 100644
--- a/packages/forms/src/model/form_array.ts
+++ b/packages/forms/src/model/form_array.ts
@@ -174,6 +174,8 @@ export class FormArray<TControl extends AbstractControl<any> = any> extends Abst
    * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
    * `valueChanges` observables emit events with the latest status and value when the control is
    * inserted. When false, no events are emitted.
+   *
+   * NOTE: Pushing to the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
    */
   push(control: TControl | Array<TControl>, options: {emitEvent?: boolean} = {}): void {
     if (Array.isArray(control)) {
@@ -201,6 +203,8 @@ export class FormArray<TControl extends AbstractControl<any> = any> extends Abst
    * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
    * `valueChanges` observables emit events with the latest status and value when the control is
    * inserted. When false, no events are emitted.
+   *
+   * NOTE: Inserting to the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
    */
   insert(index: number, control: TControl, options: {emitEvent?: boolean} = {}): void {
     this.controls.splice(index, 0, control);
@@ -220,6 +224,8 @@ export class FormArray<TControl extends AbstractControl<any> = any> extends Abst
    * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
    * `valueChanges` observables emit events with the latest status and value when the control is
    * removed. When false, no events are emitted.
+   *
+   * NOTE: Removing the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
    */
   removeAt(index: number, options: {emitEvent?: boolean} = {}): void {
     // Adjust the index, then clamp it at no less than 0 to prevent undesired underflows.