id | title | permalink | prev | next |
---|---|---|---|---|
animation |
Animation |
animation.html |
addons.html |
two-way-binding-helpers.html |
React provides a ReactTransitionGroup
addon component as a low-level API for animation, and a ReactCSSTransitionGroup
for easily implementing basic CSS animations and transitions.
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.
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 = React.addons.CSSTransitionGroup;
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;
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>
);
}
});
Note:
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.
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;
transition: opacity .5s ease-in;
}
.example-appear.example-appear-active {
opacity: 1;
}
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
.
Note:
The prop
transitionAppear
was added toReactCSSTransitionGroup
in version0.13
. To maintain backwards compatibility, the default value is set tofalse
.
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>
...
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>
);
}
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 = React.addons.CSSTransitionGroup;
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>
);
}
});
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.
Note:
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.
ReactTransitionGroup
is the basis for animations. It is accessible as React.addons.TransitionGroup
. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.
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
.
This is called after the callback
function that was passed to componentWillAppear
is called.
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
.
This is called after the callback
function that was passed to componentWillEnter
is called.
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.
This is called when the willLeave
callback
is called (at the same time as componentWillUnmount
).
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>
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!
Note:
Prior to v0.12, when using DOM components, the
component
prop needed to be a reference toReact.DOM.*
. Since the component is simply passed toReact.createElement
, it must now be a string. Composite components must pass the factory.
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>