From 565aac5abebc0b14b78346b1070464b4c5aad3e3 Mon Sep 17 00:00:00 2001
From: David Hu <davidhu91@gmail.com>
Date: Sun, 27 Jul 2014 00:26:17 -0700
Subject: [PATCH] Clarify animating one or zero items in docs

When I first read these docs, it was not immediately clear to me that I could
use `React.addons.CSSTransitionGroup` to animate a single item coming into view,
or an item replacing an item already there. This was partly due to the example
which rendered a list of items.

This PR adds a blurb about being able to use
`React.addons.CSSTransitionGroup` with one or zero items, provides a code
example, and adds a note blockquote that a `key` attribute must always be
provided on each child of `React.addons.CSSTransitionGroup`. The latter point
was not immediately obvious from the original `TodoList` code example, since it
renders a list which would normally require `key` attributes anyway.

Test Plan:
- Refreshed `http://localhost:4000/react/docs/animation.html`, saw that the
  docs additions rendered correctly.
- Example code not tested (it was extracted from working code).
---
 docs/09.1-animation.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/09.1-animation.md b/docs/09.1-animation.md
index a24fc64d..f310a13f 100644
--- a/docs/09.1-animation.md
+++ b/docs/09.1-animation.md
@@ -84,6 +84,35 @@ You'll notice that when you try to remove an item `ReactCSSTransitionGroup` keep
 }
 ```
 
+### Animating One or Zero Items
+
+Although in the example above we rendered a list of items into `ReactCSSTransitionGroup`, the children of `ReactCSSTransitionGroup` can be one or zero items. This makes it possible to animate a single element entering or leaving. Similarly, you can animate a new element replacing the current element, with the new element animating in while the current animates out. For example, we can implement a simple image carousel like this:
+
+```javascript{12-14}
+/** @jsx React.DOM */
+
+var ReactCSSTransitionGroup = React.addons.CSSTransitionGroup;
+
+var ImageCarousel = React.createClass({
+  propTypes: {
+    imageSrc: React.PropTypes.string.isRequired
+  },
+  render: function() {
+    return (
+      <div>
+        <ReactCSSTransitionGroup transitionName="carousel">
+          <img src={this.props.imageSrc} key={this.props.imageSrc} />
+        </ReactCSSTransitionGroup>
+      </div>
+    );
+  }
+});
+```
+
+> Note:
+>
+> You must provide [the `key` attribute](/react/docs/multiple-components.html#dynamic-children) for all children of `ReactCSSTransitionGroup`, even if rendering a single item. This is how React will determine which children have entered, left, or stayed.
+
 ### Disabling Animations
 
 You can disable animating `enter` or `leave` animations if you want. For example, sometimes you may want an `enter` animation and no `leave` animation, but `ReactCSSTransitionGroup` waits for an animation to complete before removing your DOM node. You can add `transitionEnter={false}` or `transitionLeave={false}` props to `ReactCSSTransitionGroup` to disable these animations.