React provides a ReactTransitionGroup
add-on component as a low-level API for animation, and a ReactCSSTransitionGroup
for easily implementing basic CSS animations and transitions.
High-level API: ReactCSSTransitionGroup
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 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.
var ReactCSSTransitionGroup = require('react-addons-css-transition-group'); var TodoList = React.createClass({ getInitialState: function() { return {items: ['hello', 'world', 'click', 'me']}; }, handleAdd: function() { var newItems = this.state.items.concat([prompt('Enter some text')]); this.setState({items: newItems}); }, handleRemove: function(i) { var newItems = this.state.items.slice(); newItems.splice(i, 1); this.setState({items: newItems}); }, render: function() { var items = this.state.items.map(function(item, i) { return ( <div key={item} onClick={this.handleRemove.bind(this, i)}> {item} </div> ); }.bind(this)); return ( <div> <button onClick={this.handleAdd}>Add Item</button> <ReactCSSTransitionGroup transitionName="example" transitionEnterTimeout={500} transitionLeaveTimeout={300}> {items} </ReactCSSTransitionGroup> </div> ); } });
You must provide the
key
attribute for all children ofReactCSSTransitionGroup
, even when only rendering a single item. This is how React will determine which children have entered, left, or stayed.
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:
.example-enter { opacity: 0.01; } .example-enter.example-enter-active { opacity: 1; transition: opacity 500ms ease-in; } .example-leave { opacity: 1; } .example-leave.example-leave-active { opacity: 0.01; transition: opacity 300ms ease-in; }
You'll notice that animation durations need to be specified in both the CSS and the render method; this tells React when to remove the animation classes from the element and -- if it's leaving -- when to remove the element from the DOM.
Animate Initial Mounting
ReactCSSTransitionGroup
provides the optional prop transitionAppear
, to add an extra transition phase at the initial mount of the component. There is generally no transition phase at the initial mount as the default value of transitionAppear
is false
. The following is an example which passes the prop transitionAppear
with the value true
.
render: function() { return ( <ReactCSSTransitionGroup transitionName="example" transitionAppear={true} transitionAppearTimeout={500}> <h1>Fading at Initial Mount</h1> </ReactCSSTransitionGroup> ); }
During the initial mount ReactCSSTransitionGroup
will get the example-appear
CSS class and the example-appear-active
CSS class added in the next tick.
.example-appear { opacity: 0.01; } .example-appear.example-appear-active { opacity: 1; transition: opacity .5s ease-in; }
At the initial mount, all children of the ReactCSSTransitionGroup
will appear
but not enter
. However, all children later added to an existing ReactCSSTransitionGroup
will enter
but not appear
.
The prop
transitionAppear
was added toReactCSSTransitionGroup
in version0.13
. To maintain backwards compatibility, the default value is set tofalse
.
Custom Classes
It is also possible to use custom class names for each of the steps in your transitions. Instead of passing a string into transitionName you can pass an object containing either the enter
and leave
class names, or an object containing the enter
, enter-active
, leave-active
, and leave
class names. If only the enter and leave classes are provided, the enter-active and leave-active classes will be determined by appending '-active' to the end of the class name. Here are two examples using custom classes:
... <ReactCSSTransitionGroup transitionName={ { enter: 'enter', enterActive: 'enterActive', leave: 'leave', leaveActive: 'leaveActive', appear: 'appear', appearActive: 'appearActive' } }> {item} </ReactCSSTransitionGroup> <ReactCSSTransitionGroup transitionName={ { enter: 'enter', leave: 'leave', appear: 'appear' } }> {item2} </ReactCSSTransitionGroup> ...
Animation Group Must Be Mounted To Work
In order for it to apply transitions to its children, the ReactCSSTransitionGroup
must already be mounted in the DOM or the prop transitionAppear
must be set to true
. The example below would not work, because the ReactCSSTransitionGroup
is being mounted along with the new item, instead of the new item being mounted within it. Compare this to the Getting Started section above to see the difference.
render: function() { var items = this.state.items.map(function(item, i) { return ( <div key={item} onClick={this.handleRemove.bind(this, i)}> <ReactCSSTransitionGroup transitionName="example"> {item} </ReactCSSTransitionGroup> </div> ); }, this); return ( <div> <button onClick={this.handleAdd}>Add Item</button> {items} </div> ); }
Animating One or Zero Items
In the example above, we rendered a list of items into ReactCSSTransitionGroup
. However, the children of ReactCSSTransitionGroup
can also 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. For example, we can implement a simple image carousel like this:
var ReactCSSTransitionGroup = require('react-addons-css-transition-group'); var ImageCarousel = React.createClass({ propTypes: { imageSrc: React.PropTypes.string.isRequired }, render: function() { return ( <div> <ReactCSSTransitionGroup transitionName="carousel" transitionEnterTimeout={300} transitionLeaveTimeout={300}> <img src={this.props.imageSrc} key={this.props.imageSrc} /> </ReactCSSTransitionGroup> </div> ); } });
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.
When using
ReactCSSTransitionGroup
, there's no way for your components to be notified when a transition has ended or to perform any more complex logic around animation. If you want more fine-grained control, you can use the lower-levelReactTransitionGroup
API which provides the hooks you need to do custom transitions.
Low-level API: ReactTransitionGroup
ReactTransitionGroup
is the basis for animations. It is accessible from require('react-addons-transition-group')
. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.
componentWillAppear(callback)
This is called at the same time as componentDidMount()
for components that are initially mounted in a TransitionGroup
. It will block other animations from occurring until callback
is called. It is only called on the initial render of a TransitionGroup
.
componentDidAppear()
This is called after the callback
function that was passed to componentWillAppear
is called.
componentWillEnter(callback)
This is called at the same time as componentDidMount()
for components added to an existing TransitionGroup
. It will block other animations from occurring until callback
is called. It will not be called on the initial render of a TransitionGroup
.
componentDidEnter()
This is called after the callback
function that was passed to componentWillEnter
is called.
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.
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>
:
<ReactTransitionGroup component="ul"> ... </ReactTransitionGroup>
Any additional, user-defined, properties will become properties of the rendered component. For example, here's how you would render a <ul>
with CSS class:
<ReactTransitionGroup component="ul" className="animated-list"> ... </ReactTransitionGroup>
Every DOM component that React can render is available for use. However, component
does not need to be a DOM component. It can be any React component you want; even ones you've written yourself! Just write component={List}
and your component will receive this.props.children
.
Rendering a Single Child
People often use ReactTransitionGroup
to animate mounting and unmounting of a single child such as a collapsible panel. Normally ReactTransitionGroup
wraps all its children in a span
(or a custom component
as described above). This is because any React component has to return a single root element, and ReactTransitionGroup
is no exception to this rule.
However if you only need to render a single child inside ReactTransitionGroup
, you can completely avoid wrapping it in a <span>
or any other DOM component. To do this, create a custom component that renders the first child passed to it directly:
var FirstChild = React.createClass({ render: function() { var children = React.Children.toArray(this.props.children); return children[0] || null; } });
Now you can specify FirstChild
as the component
prop in <ReactTransitionGroup>
props and avoid any wrappers in the result DOM:
<ReactTransitionGroup component={FirstChild}> {someCondition ? <MyComponent /> : null} </ReactTransitionGroup>
This only works when you are animating a single child in and out, such as a collapsible panel. This approach wouldn't work when animating multiple children or replacing the single child with another child, such as an image carousel. For an image carousel, while the current image is animating out, another image will animate in, so <ReactTransitionGroup>
needs to give them a common DOM parent. You can't avoid the wrapper for multiple children, but you can customize the wrapper with the component
prop as described above.
Please login to continue.