From 581877e34683e130c196c82879b692f0a790833f Mon Sep 17 00:00:00 2001
From: Cheng Lou <chenglou92@gmail.com>
Date: Fri, 11 Jul 2014 16:58:39 -0700
Subject: [PATCH] [Docs] Document PureRenderMixin addon

Fixes #1816
---
 _data/nav_docs.yml             |  2 ++
 docs/09.6-update.md            |  1 +
 docs/09.7-pure-render-mixin.md | 30 ++++++++++++++++++++++++++++++
 3 files changed, 33 insertions(+)
 create mode 100644 docs/09.7-pure-render-mixin.md

diff --git a/_data/nav_docs.yml b/_data/nav_docs.yml
index 794ad9bf..0744fa03 100644
--- a/_data/nav_docs.yml
+++ b/_data/nav_docs.yml
@@ -55,6 +55,8 @@
       title: Cloning Components
     - id: update
       title: Immutability Helpers
+    - id: pure-render-mixin
+      title: PureRenderMixin
 - title: Reference
   items:
   - id: top-level-api
diff --git a/docs/09.6-update.md b/docs/09.6-update.md
index 18f1a6f5..6f8b93be 100644
--- a/docs/09.6-update.md
+++ b/docs/09.6-update.md
@@ -4,6 +4,7 @@ title: Immutability Helpers
 layout: docs
 permalink: update.html
 prev: clone-with-props.html
+next: pure-render-mixin.html
 ---
 
 React lets you use whatever style of data management you want, including mutation. However, if you can use immutable data in performance-critical parts of your application it's easy to implement a fast `shouldComponentUpdate()` method to significantly speed up your app.
diff --git a/docs/09.7-pure-render-mixin.md b/docs/09.7-pure-render-mixin.md
new file mode 100644
index 00000000..2235dceb
--- /dev/null
+++ b/docs/09.7-pure-render-mixin.md
@@ -0,0 +1,30 @@
+---
+id: pure-render-mixin
+title: PureRenderMixin
+layout: docs
+permalink: pure-render-mixin.html
+prev: update.html
+---
+
+If your React component's render function is "pure" (in other words, it renders the same result given the same props and state), you can use this mixin for a considerable performance boost.
+
+Example:
+
+```js
+var PureRenderMixin = require('react').addons.PureRenderMixin;
+React.createClass({
+  mixins: [PureRenderMixin],
+
+  render: function() {
+    return <div className={this.props.className}>foo</div>;
+  }
+});
+```
+
+Under the hood, the mixin implements [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate), in which it compares the current props and state with the next ones and returns `false` if the equalities pass.
+
+> Note:
+>
+> This only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only mix into components which have simple props and state, or use `forceUpdate()` when you know deep data structures have changed.
+>
+> Furthermore, `shouldComponentUpdate` skips updates for the whole component subtree. Make sure all the children components are also "pure".