Clarify refs and setState callback documentation
Ben Alpert committed
Jun 17, 2014 at 23:19 UTC
121b29089916f49a0198a778eeb2236c1e639eef
2 files changed
+17
-12
docs/docs/07.1-more-about-refs.md
+15
-10
@@ -72,17 +72,19 @@ React supports a very special property that you can attach to any component that
72
73
It's as simple as:
74
75
-**1.** Assign a `ref` attribute to anything returned from `render` such as:
75
+1. Assign a `ref` attribute to anything returned from `render` such as:
76
77
-```html
78
- <input ref="myInput" />
79
-```
77
+ ```html
78
+ <input ref="myInput" />
79
+ ```
80
81
-**2.** In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
81
+2. In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
82
83
-```javascript
83
+ ```javascript
84
this.refs.myInput
85
-```
85
+ ```
86
+
87
+ You can access the component's DOM node directly by calling `this.refs.myInput.getDOMNode()`.
88
89
## Completing the Example
90
@@ -95,8 +97,11 @@ It's as simple as:
97
this.setState({userInput: e.target.value});
98
},
99
clearAndFocusInput: function() {
98
- this.setState({userInput: ''}); // Clear the input
99
- this.refs.theInput.getDOMNode().focus(); // Boom! Focused!
100
+ // Clear the input
101
+ this.setState({userInput: ''}, function() {
102
+ // This code executes after the component is re-rendered
103
+ this.refs.theInput.getDOMNode().focus(); // Boom! Focused!
104
+ });
105
},
106
render: function() {
107
return (
@@ -132,4 +137,4 @@ Refs are a great way to send a message to a particular child instance in a way t
137
138
- *Never* access refs inside of any component's render method - or while any component's render method is even running anywhere in the call stack.
139
- If you want to preserve Google Closure Compiler Crushing resilience, make sure to never access as a property what was specified as a string. This means you must access using `this.refs['myRefString']` if your ref was defined as `ref="myRefString"`.
135
-- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" - instead, the data flow will usually accomplish your goal.
140
+- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" – instead, the data flow will usually accomplish your goal.
docs/docs/ref-02-component-api.md
+2
-2
@@ -29,7 +29,7 @@ setProps(object nextProps[, function callback])
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()`.
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.
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 and the component is re-rendered.
33
34
> Note:
35
>
@@ -80,7 +80,7 @@ Properties that are specified directly on the target component instance (such as
80
setState(object nextState[, function callback])
81
```
82
83
-Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. In addition, you can supply an optional callback function that is executed once `setState` is completed.
83
+Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. In addition, you can supply an optional callback function that is executed once `setState` is completed and the component is re-rendered.
84
85
> Notes:
86
>