Skip to content

Commit

Permalink
Clarify animating one or zero items in docs
Browse files Browse the repository at this point in the history
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).
  • Loading branch information
divad12 committed Jul 27, 2014
1 parent c6b2687 commit 721f397
Showing 1 changed file with 29 additions and 0 deletions.
29 changes: 29 additions & 0 deletions docs/docs/09.1-animation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 721f397

Please sign in to comment.