React: clarify when componentDidUpdate fires.

[Pomax]

http://facebook.github.io/react/docs/component-specs.html#updating-componentdidupdate is unclear on when it is called with regards to the render function.

The docs state that it's "Invoked immediately after updating occurs" but it is unclear what is meant with updating in this case: it can refer to either the component as a whole updating (meaning post-render), or it can refer to setState() having been processed (which might mean pre-render).

It would be good to explicitly state when this function fires in its documentation (even if somewhere else on the site this is described in text or graphic form already).

[gaearon]

I think this part makes it clear it happens after DOM is updated (post-render):

Invoked immediately after updating occurs. This method is not called for the initial render.
Use this as an opportunity to operate on the DOM when the component has been updated.

However, overall I agree more descriptive (visual?) lifecycle explanation would be welcome.

[Pomax]

That's not clear enough, though. React does a good job making sure you normally don't work on the DOM, so in this case I really need explicit text that says "Use this as an opportunity to operate on the DOM after render has finished" - without that, it still entirely possible that it's offering a way to mess with the DOM _before_ updates from subsequent render calls are worked in.

[gaearon]

after render has finished

This wouldn't be entirely correct though. render doesn't do anything per se, it just builds the virtual DOM tree.

[sophiebits]

componentDidUpdate (and componentDidMount) is always called after the DOM has been updated – we can update the docs. Want to send a pull request?

[Pomax]

I'll have to read through your CLA carefully before I can file any PRs. In the mean time, any clarification you deem addresses this issue is fine by me.

[zeusdeux]

@Pomax The fact that it lets you operate on the updated DOM implies that it's post-render.

[Pomax]

@zeusdeux sure, but I'd love to know you get that from the actual words used in the text, rather than from the text you read paired with your knowledge of React.

In this case, three people went "it's after the DOM updates", so: sweet! Let's change the text from

Invoked immediately after updating occurs. This method is not called for the initial render.
Use this as an opportunity to operate on the DOM when the component has been updated

to

Invoked immediately after the component's associated DOM gets updated.
This method is not called for the initial render.
Use this as an opportunity to further operate on the DOM after a component has updated.

and now it's no longer implied, now it's explicit, and new users don't scratch their head going "what do they mean with updated? The tutorials mostly talk about updating in the sense of the state and props changing, but the text also talks about working on the DOM... this isn't clear enough".

[zeusdeux]

@Pomax looks like PR material to me :) :+1:

[Pomax]

indeed, and I'm not filing one until I've read that CLA. I have issues with CLAs, which is why I'm filing this as an issue instead, and hopefully other people working on the code find opening the docs file on github, hitting "edit", and dropping that in, not too much work.

[flyingace]

I saw that this had been closed but it appears that the documentation remains unchanged. @jimfb's PR seems to have been merged but I'm not sure what ever became of that since it was over 3 years ago. Perhaps the language was reverted to its original form?

I think the most important takeaway from @Pomax's original post is that documentation should always be as explicit as possible. The fact that two people from the React team responded by saying things along the lines of "The fact that it lets you operate on the updated DOM implies that it's post-render" highlights the problem. Nothing in documentation—especially for such a widely used library—should ever be implied because it lends to assuming that the reader has the same knowledge and understanding of the code as the people who wrote it.

[bmueller-sykes]

To chime in: is componentDidUpdate called regardless of whether there are DOM changes? In the case when render runs And there is no change between the DOM and virtual DOM, does componentDidUpdate still fire? Sorry if this should be obvious.

[RichCaloggero]

I'd like to know this as well. In my case, I change state, render is called, my component and it's child component both invoke their own render, but the parent's componentDidUpdate() is never fired. So, does this only file if the real DOM actually changed, or does it fire post-render, whether or not the real dom changed?

FYI: my real dom _did change_, but the method was never called!

Inquiring minds want to know!!

[mbrowne]

As @flyingace pointed out, the clarification in the docs seems to have been reverted and this issue should be re-opened

[gaearon]

If there is an issue with documentation, please file it in the documentation repository: https://github.com/reactjs/reactjs.org. Then we or somebody else can address it. We're not reading closed issues (it's hard enough to keep up with open ones!) so your feedback is unfortunately going into the void. Thank you!