`ReactTransitions` is an easy way to perform CSS transitions and animations when a React component enters or leaves the DOM. It's inspired by the excellent [ng-animate](http://www.nganimate.org/) library.
React provides a `ReactTransitionGroup` addon component as a low-level API for animation, and a `ReactCSSTransitionGroup` for easily implementing basic CSS animations and transitions.
## Getting Started
## High-level API: `ReactCSSTransitionGroup`
`ReactTransitionGroup` is the interface to `ReactTransitions`. This is a simple element that wraps all of the components you are interested in animating. Here's an example where we fade list items in and out.
`ReactCSSTransitionGroup` is based on `ReactTransitionGroup` and is an easy way to perform CSS transitions and animations when a React component enters or leaves the DOM. It's inspired by the excellent [ng-animate](http://www.nganimate.org/) library.
### Getting Started
`ReactCSSTransitionGroup` is the interface to `ReactTransitions`. This is a simple element that wraps all of the components you are interested in animating. Here's an example where we fade list items in and out.
```javascript{22-24}
/** @jsx React.DOM */
var ReactTransitionGroup = React.addons.TransitionGroup;
var ReactCSSTransitionGroup = React.addons.TransitionGroup;
var TodoList = React.createClass({
getInitialState: function() {
@ -43,16 +47,16 @@ var TodoList = React.createClass({
return (
<div>
<div><buttononClick={this.handleAdd}/></div>
<ReactTransitionGrouptransitionName="example">
<ReactCSSTransitionGrouptransitionName="example">
{items}
</ReactTransitionGroup>
</ReactCSSTransitionGroup>
</div>
);
}
});
```
In this component, when a new item is added to `ReactTransitionGroup` it will get the `example-enter` CSS class and the `example-enter-active` CSS class added in the next tick. This is a convention based on the `transitionName` prop.
In this component, when a new item is added to `ReactCSSTransitionGroup` it will get the `example-enter` CSS class and the `example-enter-active` CSS class added in the next tick. This is a convention based on the `transitionName` prop.
You can use these classes to trigger a CSS animation or transition. For example, try adding this CSS and adding a new list item:
@ -67,7 +71,7 @@ You can use these classes to trigger a CSS animation or transition. For example,
}
```
You'll notice that when you try to remove an item `ReactTransitionGroup` keeps it in the DOM. If you're using an unminified build of React with add-ons you'll see a warning that React was expecting an animation or transition to occur. That's because `ReactTransitionGroup` keeps your DOM elements on the page until the animation completes. Try adding this CSS:
You'll notice that when you try to remove an item `ReactCSSTransitionGroup` keeps it in the DOM. If you're using an unminified build of React with add-ons you'll see a warning that React was expecting an animation or transition to occur. That's because `ReactCSSTransitionGroup` keeps your DOM elements on the page until the animation completes. Try adding this CSS:
```css
.example-leave {
@ -80,20 +84,46 @@ You'll notice that when you try to remove an item `ReactTransitionGroup` keeps i
}
```
## Disabling Animations
### 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.
## Low-level API: `ReactTransitionGroup`
`ReactTransitionGroup` is the basis for animations. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.
### `componentWillEnter(callback)`
This is called at the same time as `componentDidMount()`. It will block other animations from occurring until `callback` is called.
### `componentDidEnter()`
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 `ReactTransitionGroup` waits for an animation to complete before removing your DOM node. You can add `transitionEnter={false}` or `transitionLeave={false}` props to `ReactTransitionGroup` to disable these animations.
This is called when the `willEnter``callback` is called.
## Rendering a Different Component
### `componentWillLeave(callback)`
This is called when the child has been removed from the `ReactTransitionGroup`. Though the child has been removed, `ReactTransitionGroup` will keep it in the DOM until `callback` is called.
Note that because the child has been removed you can no longer send it reactive updates. If you need this functionality, see the section on Child Factories below.
### `componentDidLeave()`
This is called when the `willLeave``callback` is called (at the same time as `componentWillUnmount`).
### Rendering a Different Component
By default `ReactTransitionGroup` renders as a `span`. You can change this behavior by providing a `component` prop. For example, here's how you would render a `<ul>`:
```javascript{3}
<ReactTransitionGroup
transitionName="example"
component={React.DOM.ul}>
```javascript{1}
<ReactTransitionGroupcomponent={React.DOM.ul}>
...
</ReactTransitionGroup>
```
Every DOM component is under `React.DOM`. However, `component` does not need to be a DOM component. It can be any React component you want; even ones you've written yourself!
### Advanced Feature: Child Factories
`ReactTransitionGroup` is unique because when a child leaves `ReactTransitionGroup` it may stay in the DOM after the child is removed from the group. This means that you can't send it reactive updates anymore. If you need to send it updates, you can provide a `childFactory` callback prop which will take the original child instance (even after it has left the group) and return a React component to render in its place.
Normally you do not need to think about this feature. If you do, the easiest way to understand how this works is to look at the source for `ReactCSSTransitionGroup`.
petehunt
11 years ago