diff --git a/docs/api-reference.md b/docs/api-reference.md
index a51216ca..f356bbea 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -608,4 +608,7 @@ end
As with `setState`, you can set use the constant `Roact.None` to remove a field from the state.
!!! note
- `getDerivedStateFromProps` is a *static* lifecycle method. It does not have access to `self`, and must be a pure function.
\ No newline at end of file
+ `getDerivedStateFromProps` is a *static* lifecycle method. It does not have access to `self`, and must be a pure function.
+
+!!! caution
+ `getDerivedStateFromProps` runs before `shouldUpdate` and any non-nil return will cause the state table to no longer be shallow-equal. This means that a `PureComponent` will rerender even if nothing actually changed. Similarly, any component implementing both `getDerivedStateFromProps` and `shouldUpdate` needs to do so in a way that takes this in to account.
diff --git a/docs/images/lifecycle.gv b/docs/images/lifecycle.gv
index 61c3d4e9..aff4b6f2 100644
--- a/docs/images/lifecycle.gv
+++ b/docs/images/lifecycle.gv
@@ -25,7 +25,7 @@ digraph G {