Document legacyness of the return value of ReactDOM.render()

facebook · Apr 6, 2016 · 01bab11 · 01bab11
1 parent a5c164d
commit 01bab11
Showing 1 changed file with 5 additions and 1 deletion.
diff --git a/docs/docs/ref-01-top-level-api.md b/docs/docs/ref-01-top-level-api.md
@@ -139,7 +139,7 @@ The `react-dom` package provides DOM-specific methods that can be used at the to
 ### ReactDOM.render
 
 ```javascript
-ReactComponent render(
+render(
   ReactElement element,
   DOMElement container,
   [function callback]
@@ -161,6 +161,10 @@ If the optional callback is provided, it will be executed after the component is
 > `ReactDOM.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.
+>
+> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
+> and should be avoided because future versions of React may render components asynchronously in some cases. If you need a reference to the root `ReactComponent` instance, the preferred solution is to attach a
+> [callback ref](/react/docs/more-about-refs.html#the-ref-callback-attribute) to the root element.
 
 
 ### ReactDOM.unmountComponentAtNode