Skip to content

Commit 060304c

Browse files
docs(forms): clarify zoneless change detection for reactive FormArray updates
Document that reactive forms model mutations such as FormArray.push() do not schedule component change detection in zoneless applications and show the recommended ways to notify Angular. Fixes angular#65536
1 parent 6267626 commit 060304c

2 files changed

Lines changed: 26 additions & 0 deletions

File tree

adev/src/content/guide/forms/reactive-forms.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,26 @@ The `@for` block iterates over each form control instance provided by the aliase
379379

380380
Each time a new alias instance is added, the new form array instance is provided its control based on the index. This lets you track each individual control when calculating the status and value of the root control.
381381

382+
NOTE: In zoneless applications, mutating a reactive forms model (for example calling `FormArray.push()`) does not automatically schedule component change detection. If your template depends on structural model changes such as `aliases.controls`, make sure the component notifies Angular to run change detection, for example by bridging a forms observable to `ChangeDetectorRef.markForCheck()`:
383+
384+
```ts
385+
import {ChangeDetectorRef, Component, inject} from '@angular/core';
386+
import {takeUntilDestroyed} from '@angular/core/rxjs-interop';
387+
388+
@Component({
389+
/* ... */
390+
})
391+
export class ProfileEditor {
392+
private readonly cdr = inject(ChangeDetectorRef);
393+
394+
constructor() {
395+
this.profileForm.valueChanges
396+
.pipe(takeUntilDestroyed())
397+
.subscribe(() => this.cdr.markForCheck());
398+
}
399+
}
400+
```
401+
382402
</docs-step>
383403

384404
### Using `FormArrayDirective` for top-level form arrays

adev/src/content/guide/zoneless.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,12 @@ readonly myObservableState = someObservable.pipe(pendingUntilEvent());
123123
The framework uses this service internally as well to prevent serialization until asynchronous tasks are complete. These include, but are not limited to,
124124
an ongoing Router navigation and an incomplete `HttpClient` request.
125125

126+
### Reactive forms in zoneless applications
127+
128+
Reactive forms model updates (`setValue`, `patchValue`, `FormArray.push`, and similar APIs) update form state and emit forms observables, but they do not automatically schedule component change detection.
129+
130+
If a template depends on reactive forms state, connect forms observables to a change-detection notification (for example `ChangeDetectorRef.markForCheck()`), or reflect the data through signals consumed by the template.
131+
126132
## Testing and Debugging
127133

128134
### Using Zoneless in `TestBed`

0 commit comments

Comments
 (0)