angular · crisbeto · Sep 23, 2024
diff --git a/goldens/public-api/core/index.api.md b/goldens/public-api/core/index.api.md
@@ -63,6 +63,7 @@ export function afterRenderEffect<E = never, W = never, M = never>(spec: {
 // @public
 export interface AfterRenderOptions {
     injector?: Injector;
+    manualCleanup?: boolean;
     // @deprecated
     phase?: AfterRenderPhase;
 }

diff --git a/packages/core/src/render3/after_render/hooks.ts b/packages/core/src/render3/after_render/hooks.ts
@@ -44,6 +44,14 @@ export interface AfterRenderOptions {
    */
   injector?: Injector;
 
+  /**
+   * Whether the hook should require manual cleanup.
+   *
+   * If this is `false` (the default) the hook will automatically register itself to be cleaned up
+   * with the current `DestroyRef`.
+   */
+  manualCleanup?: boolean;
+
   /**
    * The phase the callback should be invoked in.
    *
@@ -448,11 +456,12 @@ function afterRenderImpl(
   manager.impl ??= injector.get(AfterRenderImpl);
 
   const hooks = options?.phase ?? AfterRenderPhase.MixedReadWrite;
+  const destroyRef = options?.manualCleanup !== true ? injector.get(DestroyRef) : null;
   const sequence = new AfterRenderSequence(
     manager.impl,
     getHooks(callbackOrSpec, hooks),
     once,
-    injector.get(DestroyRef),
+    destroyRef,
   );
   manager.impl.register(sequence);
   return sequence;

diff --git a/packages/core/src/render3/after_render/manager.ts b/packages/core/src/render3/after_render/manager.ts
@@ -149,15 +149,15 @@ export class AfterRenderSequence implements AfterRenderRef {
    */
   pipelinedValue: unknown = undefined;
 
-  private unregisterOnDestroy: () => void;
+  private unregisterOnDestroy: (() => void) | undefined;
 
   constructor(
     readonly impl: AfterRenderImpl,
     readonly hooks: AfterRenderHooks,
     public once: boolean,
-    destroyRef: DestroyRef,
+    destroyRef: DestroyRef | null,
   ) {
-    this.unregisterOnDestroy = destroyRef.onDestroy(() => this.destroy());
+    this.unregisterOnDestroy = destroyRef?.onDestroy(() => this.destroy());
   }
 
   afterRun(): void {
@@ -167,6 +167,6 @@ export class AfterRenderSequence implements AfterRenderRef {
 
   destroy(): void {
     this.impl.unregister(this);
-    this.unregisterOnDestroy();
+    this.unregisterOnDestroy?.();
   }
 }
diff --git a/packages/core/test/acceptance/after_render_hook_spec.ts b/packages/core/test/acceptance/after_render_hook_spec.ts
@@ -715,6 +715,53 @@ describe('after render hooks', () => {
           );
         });
       });
+
+      it('should not destroy automatically if manualCleanup is set', () => {
+        let afterRenderRef: AfterRenderRef | null = null;
+        let count = 0;
+
+        @Component({selector: 'comp', template: ''})
+        class Comp {
+          constructor() {
+            afterRenderRef = afterRender(() => count++, {manualCleanup: true});
+          }
+        }
+
+        @Component({
+          imports: [Comp],
+          template: `
+            @if (shouldShow) {
+              <comp/>
+            }
+          `,
+        })
+        class App {
+          shouldShow = true;
+        }
+
+        TestBed.configureTestingModule({
+          declarations: [App, Comp],
+          ...COMMON_CONFIGURATION,
+        });
+        const component = createAndAttachComponent(App);
+        const appRef = TestBed.inject(ApplicationRef);
+        expect(count).toBe(0);
+
+        appRef.tick();
+        expect(count).toBe(1);
+
+        component.instance.shouldShow = false;
+        component.changeDetectorRef.detectChanges();
+        appRef.tick();
+        expect(count).toBe(2);
+        appRef.tick();
+        expect(count).toBe(3);
+
+        // Ensure that manual destruction still works.
+        afterRenderRef!.destroy();
+        appRef.tick();
+        expect(count).toBe(3);
+      });
     });
 
     describe('afterNextRender', () => {