[docs] Point to renderComponent over setProps
Ben Alpert committed
Jun 8, 2014 at 13:04 UTC
2f61996ec30245182c3b783986c2b3b8f50265a0
1 file changed
+5
-1
docs/docs/ref-02-component-api.md
+5
-1
@@ -27,10 +27,14 @@ If this component has been mounted into the DOM, this returns the corresponding
27
setProps(object nextProps[, function callback])
28
```
29
30
-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.
30
+When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`.
31
+
32
+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.
33
34
> Note:
35
>
36
+> 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.)
37
+>
38
> 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()`.
39
40