From bcaebecce2757f0f26cd07a93ffce724bd6c3dac Mon Sep 17 00:00:00 2001 From: Ben Alpert Date: Sun, 8 Jun 2014 13:04:40 -0700 Subject: [PATCH] [docs] Point to renderComponent over setProps (cherry picked from commit 2f61996ec30245182c3b783986c2b3b8f50265a0) --- docs/docs/ref-02-component-api.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docs/ref-02-component-api.md b/docs/docs/ref-02-component-api.md index 442f310680..f1efc969cd 100644 --- a/docs/docs/ref-02-component-api.md +++ b/docs/docs/ref-02-component-api.md @@ -27,10 +27,14 @@ If this component has been mounted into the DOM, this returns the corresponding setProps(object nextProps[, function callback]) ``` -When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`. Simply call `setProps()` to change its properties and trigger a re-render. In addition, you can supply an optional callback function that is executed once `setProps` is completed. +When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`. + +Though calling `React.renderComponent()` again on the same node is the preferred way to update a root-level component, you can also call `setProps()` to change its properties and trigger a re-render. In addition, you can supply an optional callback function that is executed once `setProps` is completed. > Note: > +> When possible, the declarative approach of calling `React.renderComponent()` again is preferred; it tends to make updates easier to reason about. (There's no significant performance difference between the two approaches.) +> > This method can only be called on a root-level component. That is, it's only available on the component passed directly to `React.renderComponent()` and none of its children. If you're inclined to use `setProps()` on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in `render()`.