Skip to content

Commit 1474f7a

Browse files
marnuswmarnusw
committed
Docs for v1.0.0.
1 parent 7fc546a commit 1474f7a

File tree

3 files changed

+114
-38
lines changed

3 files changed

+114
-38
lines changed

‎CHANGELOG.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
### v1.0.0 (26 October 2015)
1+
### v1.0.0 (8 November 2015)
22

33
* [ENHANCEMENT] Added a demo page; to view run `npm install` and `gulp demo`.
44
* [ENHANCEMENT] Allow in place transitions fully configurable in CSS.
5+
* [ENHANCEMENT] Use `ReactCSSTransitionGroupChild` rather than defining yet another child wrapper.
56
* [ENHANCEMENT] More stable implementation which does not call `setState` in `componentDidUpdate` among other improvements.
67

7-
### v0.2.1 (10 October 2015)
8+
### v0.2.1 (26 October 2015)
89

910
* [UPGRADE] Upgrade React.js to v0.14.0.
1011

‎README.md‎

Lines changed: 100 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,20 @@
33
A [React](http://facebook.github.io/react/) component to animate replacing one element with another.
44

55
While [`ReactCSSTransitionGroup`](https://facebook.github.io/react/docs/animation.html) does a great job
6-
of animating changes to a list of elements it does not allow removing an element, waiting for its leave
7-
transition to complete, and then adding a new element with its enter transition. This component is
8-
designed to do exactly that with an API closely following the
9-
[`ReactCSSTransitionGroup`](https://facebook.github.io/react/docs/animation.html) API.
6+
of animating changes to a list of components and can even be used to animate the replacement of one item
7+
with another, proper handling of the container height in the latter case is not built in. This component
8+
is designed to do exactly that with an API closely following that of `ReactCSSTransitionGroup`.
9+
10+
Using `react-css-transition-replace` provides two distinct benefits:
11+
12+
- It automatically handles the positioning of the animated components internally, and
13+
- *allows changes in the height of container to be handled and animated with ease when
14+
various content heights differ, even when absolute positioning is used.*
15+
16+
Animations are fully configurable with CSS, including having the entering component wait to enter until
17+
the leaving component's animation completes. Following suit with the
18+
[React.js API](https://facebook.github.io/react/docs/animation.html#getting-started) the one caveat is
19+
that the transition duration must be specified in JavaScript as well as CSS.
1020

1121

1222
## Installation
@@ -17,65 +27,123 @@ Install via `npm`:
1727
npm install --save react-css-transition-replace
1828
```
1929

20-
**Note:** This version requires `React 0.14.0-rc1`, for `React 0.13.x` use version `0.1.4` of this library.
21-
2230

2331
## Usage
2432

25-
A `ReactCSSTransitionReplace` element can only have a single child. Other than that, the basic usage
26-
follows the exact same API as `ReactCSSTransitionGroup`:
33+
A `ReactCSSTransitionReplace` component can only have a single child. Other than that, the basic usage
34+
follows the exact same API as `ReactCSSTransitionGroup`. When the `key` of the child component changes, the
35+
previous component is animated out and the new component animated in. During this process:
36+
37+
- The leaving component continues to be rendered as usual with `static` positioning.
38+
- The entering component is positioned on top of the leaving component with `absolute` positioning.
39+
- The height of the container is set to that of the leaving component, and then immediately to that of the
40+
entering component, and the `{animation-name}-height` class is applied to it.
41+
42+
This provides many possibilities for animating the replacement as illustrated in the following examples.
43+
44+
### Cross-fading two components
45+
46+
The `ReactCSSTransitionReplace` component is used exactly like its `ReactCSSTransitionGroup` counterpart:
2747

2848
```javascript
2949
import ReactCSSTransitionReplace from 'react-css-transition-replace';
3050

3151
render() {
3252
return (
33-
<div>
34-
<ReactCSSTransitionReplace transitionName="fade">
35-
<SomeComponent />
36-
</ReactCSSTransitionReplace>
37-
</div>
53+
<ReactCSSTransitionReplace transitionName="cross-fade"
54+
transitionEnterTimeout={1000} transitionLeaveTimeout={1000}>
55+
<SomeComponent key="uniqueValue"/>
56+
</ReactCSSTransitionReplace>
3857
);
3958
}
4059
```
4160

42-
This will use the CSS styles below to apply transitions to the child elements that leave and enter.
43-
The entering element will only be added to the DOM flow once the leaving element has been removed.
61+
To realize cross-fading of two components all that remains is to define the enter and leave opacity
62+
transitions in the associated CSS classes:
4463

4564
```css
46-
.fade-leave {
65+
.cross-fade-leave {
4766
opacity: 1;
4867
}
49-
.fade-leave.fade-leave-active {
50-
opacity: 0.01;
51-
transition: opacity .1s ease-in;
68+
.cross-fade-leave.cross-fade-leave-active {
69+
opacity: 0;
70+
transition: opacity 1s ease-in;
5271
}
5372

54-
.fade-enter {
55-
opacity: 0.01;
73+
.cross-fade-enter {
74+
opacity: 0;
5675
}
57-
.fade-enter.fade-enter-active {
76+
.cross-fade-enter.cross-fade-enter-active {
5877
opacity: 1;
59-
transition: opacity .2s ease-in;
78+
transition: opacity 1s ease-in;
6079
}
6180

62-
.fade-height {
63-
transition: height .15s ease-in-out;
81+
.cross-fade-height {
82+
transition: height 1s ease-in-out;
6483
}
6584
```
6685

67-
Note the additional `.fade-height` class. This will also animate the change in the container
68-
height based on the content transitioning out/in.
86+
Note the additional `.cross-fade-height` class. This indicates how the container height is to be
87+
animated if the heights of the entering and leaving components are not the same.
88+
89+
### Fade out, then fade in
6990

70-
It the `.fade-height` class is not specified the change in container height will not be animated.
71-
If this is the desired result the height transition can be disabled entirely by setting the
72-
`transitionHeight` prop to `false`:
91+
To fade a component out and wait for its transition to complete before fading in the next, simply
92+
add a delay to the `enter` transition.
93+
94+
```css
95+
.fade-wait-leave {
96+
opacity: 1;
97+
}
98+
.fade-wait-leave.fade-wait-leave-active {
99+
opacity: 0;
100+
transition: opacity .4s ease-in;
101+
}
73102

103+
.fade-wait-enter {
104+
opacity: 0;
105+
}
106+
.fade-wait-enter.fade-wait-enter-active {
107+
opacity: 1;
108+
/* Delay the enter animation until the leave completes */
109+
transition: opacity .4s ease-in .6s;
110+
}
111+
112+
.fade-wait-height {
113+
transition: height .6s ease-in-out;
114+
}
74115
```
75-
<ReactCSSTransitionReplace transitionName="fade" transitionHeight={false}>
116+
117+
*Note:* The `transitionEnterTimeout` specified in the JS must be long enough to allow for the delay and
118+
the duration of the transition. In this case:
119+
120+
```javascript
121+
<ReactCSSTransitionReplace transitionName="fade-wait" transitionEnterTimeout={1000} transitionLeaveTimeout={400}>
76122
```
77123

78-
The `transitionEnter`, `transitionLeave` and `transitionAppear` props are also still available.
124+
125+
#### Disabling the height transition
126+
127+
If the `.*-height` class is not specified the change in container height will not be animated but rather
128+
jump to the height of the entering component instantaneously. While this is probably not a very useful
129+
scenario in practice, doing so does not break anything and still avoids absolute positioning related
130+
height issues.
131+
132+
133+
## Tips
134+
135+
- In general animating `block` or `inline-block` level elements is more stable that `inline` elements. If the
136+
height changes in random ways ensure that there isn't a `span` or other inline element used as the outer
137+
element of the components being animated.
138+
- The `overflow` of the container is set to `'hidden'` automatically, which changes the behaviour of
139+
[collapsing margins](https://css-tricks.com/what-you-should-know-about-collapsing-margins/) from the default
140+
`'visible'`. This may cause a glitch in the height at the start or end of animations. To avoid this you can:
141+
- Keep the overflow hidden permanently with custom styles/classes if there won't be adverse side-effects.
142+
- Only use
143+
[Single-direction margin declarations](http://csswizardry.com/2012/06/single-direction-margin-declarations/)
144+
to avoid any collapsing margins.
145+
- Turn this feature off by setting the `overflowHidden={false}` prop when hidden overflow is not needed,
146+
for example when transitions are in place and content is of the same height.
79147

80148

81149
## Contributing

‎UPGRADE_GUIDE.md‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,15 @@
1-
Upgrade Guide
2-
=============
1+
# Upgrade Guide
32

4-
0.2.x -> 1.0.0
5-
--------------
3+
## 0.2.x -> 1.0.0
4+
5+
#### Specify the transition delay
6+
7+
With the upgrade of React.js from `0.13.x` to `0.14.0` the API has been updated to match
8+
that of `ReactCSSTransitionGroup` in that it requires specifying the transition duration
9+
in JS with the timeout props: `transitionEnterTimeout`, `transitionLeaveTimeout` and
10+
`transitionAppearTimeout`.
11+
12+
#### Waiting for `leave` before starting `enter`
613

714
If you were using this component to expressly wait for the leaving child to transition
815
out completely before the entering child transitions in you simply need to add a delay

0 commit comments

Comments
 (0)