What's the difference between markForCheck() and detectChanges()

What is the difference between ChangeDetectorRef.markForCheck() and ChangeDetectorRef.detectChanges()?

I only found information on SO as to the difference between NgZone.run(), but not between these two functions.

For answers with only a reference to the doc, please illustrate some practical scenarios to choose one over the other.

detectChanges() : void

Checks the change detector and its children.

It means, if there is a case where any thing inside your model (your class) has changed but it hasn't reflected the view, you might need to notify Angular to detect those changes (detect local changes) and update the view.

Possible scenarios might be :

1- The change detector is detached from the view ( see detach )

2- An update has happened but it hasn't been inside the Angular Zone, therefore, Angular doesn't know about it.

Like when a third party function has updated your model and you want to update the view after that.

 someFunctionThatIsRunByAThirdPartyCode(){
     yourModel.text = "new text";
 }

Because this code is outside of Angular's zone (probably), you most likely need to make sure to detect the changes and update the view, thus:

 myFunction(){
   someFunctionThatIsRunByAThirdPartyCode();

   // Let's detect the changes that above function made to the model which Angular is not aware of.
    this.cd.detectChanges();
 }

NOTE :

There are other ways to make above work, in other words, there are other ways to bring that change inside Angular change cycle.

** You could wrap that third party function inside a zone.run :

 myFunction(){
   this.zone.run(this.someFunctionThatIsRunByAThirdPartyCode);
 }

** You could wrap the function inside a setTimeout :

myFunction(){
   setTimeout(this.someFunctionThatIsRunByAThirdPartyCode,0);
 }

3- There are also cases where you update the model after the change detection cycle is finished, where in those cases you get this dreaded error :

"Expression has changed after it was checked";

This generally means (from Angular2 language) :

I saw an change in your model that was caused by one of my accepted ways ( events, XHR requests, setTimeout, and ... ) and then I ran my change detection to update your view and I finished it, but then there was another function in your code which updated the model again and I don't wanna run my change detection again because there is no dirty checking like AngularJS anymore :D and we should use one way data flow!

You'll definitely come across this error :P .

Couple of ways to fix it :

1- Proper way : make sure that update is inside the change detection cycle ( Angular2 updates are one way flow that happen once, do not update the model after that and move your code to a better place/time ).

2- Lazy way: run detectChanges() after that update to make angular2 happy, this is definitely not the best way, but as you asked what are the possible scenarios, this is one of them.

This way you're saying : I sincerely know you ran the change detection, but I want you to do it again because I had to update something on the fly after you finished the checking.

3- Put the code inside a setTimeout, because setTimeout is patched by zone and will run detectChanges after it's finished.

From the docs

markForCheck() : void

Marks all ChangeDetectionStrategy ancestors as to be checked.

This is mostly needed when the ChangeDetectionStrategy of your component is OnPush.

OnPush itself means, only run the change detection if any of these has happened :

1- One of the @inputs of the component has been completely replaced with a new value, or simply put, if the reference of the @Input property has changed altogether.

So if ChangeDetectionStrategy of your component is OnPush and then you have :

   var obj = {
     name:'Milad'
   };

And then you update/mutate it like :

  obj.name = "a new name";

This will not update the obj reference ,hence the change detection is not gonna run, therefore the view is not reflecting the update/mutation.

In this case you have to manually tell Angular to check and update the view (markForCheck);

So if you did this :

  obj.name = "a new name";

You need to do this:

  this.cd.markForCheck();

Rather, below would cause a change detection to run :

    obj = {
      name:"a new name"
    };

Which completely replaced the previous obj with a new {};

2- An event has fired, like a click or some thing like that or any of the child components has emitted an event.

Events like :

• Click
• Keyup
• Subscription events
• etc.

So in short :

• Use detectChanges() when you've updated the model after angular has run it's change detection, or if the update hasn't been in angular world at all.

• Use markForCheck() if you're using OnPush and you're bypassing the ChangeDetectionStrategy by mutating some data or you've updated the model inside a setTimeout;

The biggest difference between the two is that detectChanges() actually triggers change detection, while markForCheck() doesn't trigger change detection.

detectChanges

This one is used to run change detection for the tree of components starting with the component that you trigger detectChanges() on. So the change detection will run for the current component and all its children. Angular holds references to the root component tree in the ApplicationRef and when any async operation happens it triggers change detection on this root component through a wrapper method tick():

@Injectable()
export class ApplicationRef_ extends ApplicationRef {
  ...
  tick(): void {
    if (this._runningTick) {
      throw new Error('ApplicationRef.tick is called recursively');
    }

    const scope = ApplicationRef_._tickScope();
    try {
      this._runningTick = true;
      this._views.forEach((view) => view.detectChanges()); <------------------

view here is the root component view. There can be many root components as I described in the What are the implications of bootstrapping multiple components.

@milad described the reasons why you potentially could need to trigger change detection manually.

markForCheck

As I said, this guy doesn't trigger change detection at all. It simply goes upwards from the current component to the root component and updates their view state to ChecksEnabled. Here is the source code:

export function markParentViewsForCheck(view: ViewData) {
  let currView: ViewData|null = view;
  while (currView) {
    if (currView.def.flags & ViewFlags.OnPush) {
      currView.state |= ViewState.ChecksEnabled;  <-----------------
    }
    currView = currView.viewContainerParent || currView.parent;
  }
}

The actual change detection for the component is not scheduled but when it will happen in the future (either as part of the current or next CD cycle) the parent component views will be checked even if they had detached change detectors. Change detectors can be detached either by using cd.detach() or by specifying OnPush change detection strategy. All native event handlers mark all parent component views for check.

This approach is often used in the ngDoCheck lifecycle hook. You can read more in the If you think ngDoCheck means your component is being checked — read this article.

See also Everything you need to know about change detection in Angular for more details.

cd.detectChanges() will run change detection immediately from the current component down through its descendants.

cd.markForCheck() will not run change detection, but mark its ancestors as needing to run change detection. Next time change detection runs anywhere, it will run also for those components which were marked.

• If you want to reduce the number of times change detection is called use cd.markForCheck(). Often, changes affect multiple components and somewhere change detection will be called. You're essentially saying: let's just make sure this component is also updated when that happens. (The view is immediately updated in every project I've written, but not in every unit test).
• If you can't be sure that cd.detectChanges() isn't currently running change detection, use cd.markForCheck(). detectChanges() will error in that case. This probably means you trying to edit the state of an ancestor component, which is working against the assumptions that Angular's change detection are designed around.
• If it's critical that the view update synchronously before some other action, use detectChanges(). markForCheck() may not actually update your view in time. Unit testing something affects your view, for example, may require you manually call fixture.detectChanges() when that wasn't necessary in the app itself.
• If you are changing the state in a component with more ancestors than descendants you may get a performance increase by using detectChanges() since you aren't unnecessarily running change detection on the component's ancestors.

I've created a 4min screencast to explain the difference between markForCheck() and detectChanges() - https://www.youtube.com/watch?v=OcphK_aEd7I