From 7f1cfcbc979705bca93ae9e7b803eed7e2b2812e Mon Sep 17 00:00:00 2001 From: arturovt Date: Wed, 20 May 2026 20:56:03 +0300 Subject: [PATCH] docs: clarify ngDoCheck invocation behavior with OnPush strategy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous documentation for `DoCheck` / `ngDoCheck` implied that the default change-detector had run on the directive itself, which is misleading. `ngDoCheck` is actually invoked when the *parent's* change-detector checks the directive's input bindings — meaning it fires even for `OnPush` components whose own change detection was skipped. Updated three places in lifecycle_hooks.ts: - Interface description: scopes "the check" to input bindings in the parent template and adds an explicit OnPush callout. - "detects changes" clarified to "detects changes to the directive's input bindings". - Method description: "after the default change-detector runs" → "after the default change-detector has checked the directive's input bindings in the parent template". Fixes #48140 (cherry picked from commit ca44055166197449ff27eafc6af37e7734043da9) --- .../core/src/change_detection/lifecycle_hooks.ts | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/packages/core/src/change_detection/lifecycle_hooks.ts b/packages/core/src/change_detection/lifecycle_hooks.ts index 4a61dc26e8e..d0f15e9509e 100644 --- a/packages/core/src/change_detection/lifecycle_hooks.ts +++ b/packages/core/src/change_detection/lifecycle_hooks.ts @@ -76,14 +76,19 @@ export interface OnInit { /** * A lifecycle hook that invokes a custom change-detection function for a directive, - * in addition to the check performed by the default change-detector. + * in addition to the check performed by the default change-detector on the input + * bindings for this directive usage in the parent template. Note that this hook is + * invoked even when the directive's own change detection is skipped (e.g., with + * the `OnPush` change detection strategy). Developers might use this hook to + * implement a custom change detection strategy for some of the inputs. * * The default change-detection algorithm looks for differences by comparing * bound-property values by reference across change detection runs. You can use this * hook to check for and respond to changes by some other means. * - * When the default change detector detects changes, it invokes `ngOnChanges()` if supplied, - * regardless of whether you perform additional change detection. + * When the default change detector detects changes to the directive's input bindings, + * it invokes `ngOnChanges()` if supplied, regardless of whether you perform + * additional change detection. * Typically, you should not use both `DoCheck` and `OnChanges` to respond to * changes on the same input. * @@ -104,7 +109,8 @@ export interface OnInit { export interface DoCheck { /** * A callback method that performs change-detection, invoked - * after the default change-detector runs. + * after the default change-detector has checked the directive's input + * bindings in the parent template. * See `KeyValueDiffers` and `IterableDiffers` for implementing * custom change checking for collections. *