From 2ab43c462e60994a2e785d13386ff8ef3d9210f1 Mon Sep 17 00:00:00 2001
From: Kunal Mehta <k.mehta@berkeley.edu>
Date: Thu, 30 Jan 2014 17:08:29 -0800
Subject: [PATCH] Add documentation about React.renderComponent

Recently learned that components passed into `React.renderComponent` may not be the ones actually mounted. Also learned that it returns the mounted component. Added some documentation describing this.
---
 docs/ref-01-top-level-api.md        |  2 +-
 tips/16-references-to-components.md | 31 +++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 tips/16-references-to-components.md

diff --git a/docs/ref-01-top-level-api.md b/docs/ref-01-top-level-api.md
index 4d64d00d8..48f764170 100644
--- a/docs/ref-01-top-level-api.md
+++ b/docs/ref-01-top-level-api.md
@@ -46,7 +46,7 @@ ReactComponent renderComponent(
 )
 ```
 
-Render a React component into the DOM in the supplied `container`.
+Render a React component into the DOM in the supplied `container` and return a reference to the component.
 
 If the React component was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.
 
diff --git a/tips/16-references-to-components.md b/tips/16-references-to-components.md
new file mode 100644
index 000000000..38572276e
--- /dev/null
+++ b/tips/16-references-to-components.md
@@ -0,0 +1,31 @@
+---
+id: references-to-components
+title: References to Components
+layout: tips
+permalink: references-to-components.html
+prev: expose-component-functions.html
+---
+
+If you're using React components in a larger non-React application or transitioning your code to React, you may need to keep references to components. `React.renderComponent` returns a reference to the mounted component:
+
+```js
+/** @jsx React.DOM */
+
+var myComponent = React.renderComponent(<MyComponent />, myContainer);
+```
+
+If you pass a variable to 'React.renderComponent`, it's not guaranteed that the component passed in will be the one that's mounted. In cases where you construct a component before mounting it, be sure to reassign your variable:
+
+```js
+/** @jsx React.DOM */
+
+var myComponent = <MyComponent />;
+
+// Some code here...
+
+myComponent = React.renderComponent(myComponent, myContainer);
+```
+
+> Note:
+>
+> This should only ever be used at the top level. Inside components, let your `props` and `state` handle communication with child components, and only reference components via `ref`s.