From 8d480e1a47fb92d5956a6c65009c7d03744a20e8 Mon Sep 17 00:00:00 2001 From: petehunt Date: Wed, 12 Feb 2014 11:13:23 -0800 Subject: [PATCH] add ReactCSSTransitionGroup to addons and document it --- docs/09.1-animation.md | 60 +++++++++++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 15 deletions(-) diff --git a/docs/09.1-animation.md b/docs/09.1-animation.md index c3d6c23f..a08968ec 100644 --- a/docs/09.1-animation.md +++ b/docs/09.1-animation.md @@ -7,16 +7,20 @@ prev: addons.html next: two-way-binding-helpers.html --- -`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 (
- + {items} - +
); } }); ``` -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 `