From d731a058e4022e0259adfdbfcf7365201c4817a5 Mon Sep 17 00:00:00 2001
From: Edvin Erikson <edvin@rocketblast.com>
Date: Sat, 15 Aug 2015 17:03:21 +0200
Subject: [PATCH] Added documentation about pooled events

---
 docs/ref-05-events.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/ref-05-events.md b/docs/ref-05-events.md
index 2a0ab348..e271f483 100644
--- a/docs/ref-05-events.md
+++ b/docs/ref-05-events.md
@@ -33,11 +33,36 @@ string type
 >
 > 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.
 
+## Event pooling
+
+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.  
+This is for performance reasons.  
+As such, you cannot access the event in an asynchronous way.
+
+```javascript
+function onClick(event) {
+  console.log(event); // => nullified object.
+  console.log(event.type); // => "click"
+  var eventType = event.type; // => "click"
+
+  setTimeout(function() {
+    console.log(event.type); // => null
+    console.log(eventType); // => "click"
+  }, 0);
+
+  this.setState({clickEvent: event}); // Won't work. this.state.clickEvent will only contain null values.
+  this.setState({eventType: event.type}); // You can still export event properties.
+}
+```
+
+> Note:
+>
+> 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.
 
 ## Supported Events
 
 React normalizes events so that they have consistent properties across
-different browsers. 
+different browsers.
 
 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.