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(, 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 = ; + +// 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.