Documentation of React.render seems to self-contradict

[vp2177]

Correct me if I misunderstood something, but the documentation of the React.render method says:

If the ReactElement was previously rendered into container, this will perform an update on it and only mutate the DOM as necessary[...]

But later...

Note: React.render() replaces the contents of the container node you pass in.[...]

In practice, what seems to happen corresponds with the Note

[jimfb]

The documentation is not contradictory. If you call render twice with the same element, the second invocation will effectively be a no-op (because there is nothing to update). If you pass in a similar element (same type, but maybe with a different property for instance, resulting in a slightly different render result), the DOM will be updated. The documentation is correct in description of this behavior.

The note is saying that if your container already has some random DOM nodes in it before you invoke an initial render, those nodes will be blown away.

Since the documentation is not self-contradicting and is merely describing a behavior (and edge cases) that requires the reader to be semantically careful in their reading of the API, I'm inclined to close this issue. Having said that, I'm curious if you have a proposed wording that would have been more clear to you.

[vp2177]

Perhaps

React.render() replaces the contents of the container node if they didn't originate from a previous call to it.

[jimfb]

That new wording isn't technically true either (though I suppose not worse than the existing wording), because if you mutate the nodes in the container after initial render, those changes may or may not be blown away.

I think another point the note is trying to indicate is that the update has the effect of rendering the specified element INTO the container (children), rather than AS the container (updating the element in place). Lots of people mistakenly think that React.render() will update the node passed in (for instance, if they pass in a component that ultimately renders to a body node, and mount that to the body, they think it will replace the body instead of attempting to insert the rendered body node INTO the the existing body node).

[jimfb]

Perhaps if we said:

React.render() replaces the contents/children of the container node you pass in, rather than updating the container node itself. In the future, it may be possible to insert a component to an existing DOM node without overwriting the existing children.

Unclear if that actually solves your initial complaint though.

[waldreiter]

This part of the docs was misunderstood many times. I would suggest to give an example to make things more clear.

In the future, it may be possible to insert a component to an existing DOM node without overwriting the existing children.

Maybe this can get removed here? Sounds like it belongs into react-future.

[RoyalIcing]

React.render() controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient updates.

[jimfb]

React.render() controls the contents of the container node you pass in*. Any existing DOM elements inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient updates.

* React.render() does not modify the container node (only modifies the children of the container). In the future, it may be possible to insert a component to an existing DOM node without overwriting the existing children.

[KevinTCoughlin]

@jimfb I've opened a PR if the text you supplied above is final. Cheers!