Added documentation about pooled events
Edvin Erikson committed
Aug 15, 2015 at 17:03 UTC
1e3c3e1b6b798df5ffc4d8b964d61d7ad1a76b9e
1 file changed
+26
-1
docs/docs/ref-05-events.md
+26
-1
@@ -33,11 +33,36 @@ string type
33
>
34
> As of v0.12, returning `false` from an event handler will no longer stop event propagation. Instead, `e.stopPropagation()` or `e.preventDefault()` should be triggered manually, as appropriate.
35
36
+## Event pooling
37
+
38
+The `SyntheticEvent` is pooled. This means that the `SyntheticEvent` object will be reused and all properties will be nullified after the event callback has been invoked.
39
+This is for performance reasons.
40
+As such, you cannot access the event in an asynchronous way.
41
+
42
+```javascript
43
+function onClick(event) {
44
+ console.log(event); // => nullified object.
45
+ console.log(event.type); // => "click"
46
+ var eventType = event.type; // => "click"
47
+
48
+ setTimeout(function() {
49
+ console.log(event.type); // => null
50
+ console.log(eventType); // => "click"
51
+ }, 0);
52
+
53
+ this.setState({clickEvent: event}); // Won't work. this.state.clickEvent will only contain null values.
54
+ this.setState({eventType: event.type}); // You can still export event properties.
55
+}
56
+```
57
+
58
+> Note:
59
+>
60
+> If you want to access event properties in an asynchronous way, you need to create a new object e.g `var copiedEvent = assign({}, event);` or assign the specific properties to variables.
61
62
## Supported Events
63
64
React normalizes events so that they have consistent properties across
40
-different browsers.
65
+different browsers.
66
67
The event handlers below are triggered by an event in the bubbling phase. To register an event handler for the capture phase, append `Capture` to the event name; for example, instead of using `onClick`, you would use `onClickCapture` to handle the click event in the capture phase.
68