|
| 1 | +# Migration Guide from v1 to v2 |
| 2 | + |
| 3 | +_A few notes to help with migrating from v1 to v2._ |
| 4 | + |
| 5 | +The `<CSSTransitionGroup>` component has been removed. A `<CSSTransition>` component has been added for use with the new `<TransitionGroup>` component to accomplish the same tasks. |
| 6 | + |
| 7 | +### tl;dr: |
| 8 | + |
| 9 | +- `transitionName` -> `classNames` |
| 10 | +- `transitionEnterTimeout` and `transitionLeaveTimeout` -> `timeout={{ exit, enter }}` |
| 11 | +- `transitionAppear` -> `appear` |
| 12 | +- `transitionEnter` -> `enter` |
| 13 | +- `transitionLeave` -> `exit` |
| 14 | + |
| 15 | +## Walkthrough |
| 16 | + |
| 17 | +Let's take the [original docs example](https://github.com/reactjs/react-transition-group/tree/v1-stable/#high-level-api-csstransitiongroup) and migrate it. |
| 18 | + |
| 19 | +Starting with this CSS: |
| 20 | + |
| 21 | +```css |
| 22 | +.example-enter { |
| 23 | + opacity: 0.01; |
| 24 | +} |
| 25 | + |
| 26 | +.example-enter.example-enter-active { |
| 27 | + opacity: 1; |
| 28 | + transition: opacity 500ms ease-in; |
| 29 | +} |
| 30 | + |
| 31 | +.example-leave { |
| 32 | + opacity: 1; |
| 33 | +} |
| 34 | + |
| 35 | +.example-leave.example-leave-active { |
| 36 | + opacity: 0.01; |
| 37 | + transition: opacity 300ms ease-in; |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +And this component: |
| 42 | + |
| 43 | +```js |
| 44 | +class TodoList extends React.Component { |
| 45 | + constructor(props) { |
| 46 | + super(props); |
| 47 | + this.state = {items: ['hello', 'world', 'click', 'me']}; |
| 48 | + this.handleAdd = this.handleAdd.bind(this); |
| 49 | + } |
| 50 | + |
| 51 | + handleAdd() { |
| 52 | + const newItems = this.state.items.concat([ |
| 53 | + prompt('Enter some text') |
| 54 | + ]); |
| 55 | + this.setState({items: newItems}); |
| 56 | + } |
| 57 | + |
| 58 | + handleRemove(i) { |
| 59 | + let newItems = this.state.items.slice(); |
| 60 | + newItems.splice(i, 1); |
| 61 | + this.setState({items: newItems}); |
| 62 | + } |
| 63 | + |
| 64 | + render() { |
| 65 | + const items = this.state.items.map((item, i) => ( |
| 66 | + <div key={item} onClick={() => this.handleRemove(i)}> |
| 67 | + {item} |
| 68 | + </div> |
| 69 | + )); |
| 70 | + |
| 71 | + return ( |
| 72 | + <div> |
| 73 | + <button onClick={this.handleAdd}>Add Item</button> |
| 74 | + <CSSTransitionGroup |
| 75 | + transitionName="example" |
| 76 | + transitionEnterTimeout={500} |
| 77 | + transitionLeaveTimeout={300}> |
| 78 | + {items} |
| 79 | + </CSSTransitionGroup> |
| 80 | + </div> |
| 81 | + ); |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +The most straightforward way to migrate is to use `<TransitionGroup>` instead of `<CSSTransitionGroup>`: |
| 87 | + |
| 88 | +```diff |
| 89 | + render() { |
| 90 | + const items = this.state.items.map((item, i) => ( |
| 91 | + <div key={item} onClick={() => this.handleRemove(i)}> |
| 92 | + {item} |
| 93 | + </div> |
| 94 | + )); |
| 95 | + |
| 96 | + return ( |
| 97 | + <div> |
| 98 | + <button onClick={this.handleAdd}>Add Item</button> |
| 99 | +- <CSSTransitionGroup |
| 100 | +- transitionName="example" |
| 101 | +- transitionEnterTimeout={500} |
| 102 | +- transitionLeaveTimeout={300}> |
| 103 | ++ <TransitionGroup> |
| 104 | + {items} |
| 105 | +- </CSSTransitionGroup> |
| 106 | ++ </TransitionGroup> |
| 107 | + </div> |
| 108 | + ) |
| 109 | + } |
| 110 | +``` |
| 111 | + |
| 112 | +That doesn't get us much, since we haven't included anything to do the animation. For that, we'll need to wrap each item in a `<CSSTransition>`. First, though, let's adjust our CSS: |
| 113 | + |
| 114 | +```diff |
| 115 | + .example-enter { |
| 116 | + opacity: 0.01; |
| 117 | + } |
| 118 | + |
| 119 | + .example-enter.example-enter-active { |
| 120 | + opacity: 1; |
| 121 | + transition: opacity 500ms ease-in; |
| 122 | + } |
| 123 | + |
| 124 | +-.example-leave { |
| 125 | ++.example-exit { |
| 126 | + opacity: 1; |
| 127 | + } |
| 128 | + |
| 129 | +-.example-leave.example-leave-active { |
| 130 | ++.example-exit.example-exit-active { |
| 131 | + opacity: 0.01; |
| 132 | + transition: opacity 300ms ease-in; |
| 133 | + } |
| 134 | +``` |
| 135 | + |
| 136 | +All we did was replace `leave` with `exit`. v2 uses "exit" instead of "leave" to be more symmetric, avoiding awkwardness with English tenses (like with "entered" and "leaved"). |
| 137 | + |
| 138 | +Now we add the `<CSSTransition>` component: |
| 139 | + |
| 140 | +```diff |
| 141 | + render() { |
| 142 | + const items = this.state.items.map((item, i) => ( |
| 143 | ++ <CSSTransition |
| 144 | ++ key={item} |
| 145 | ++ classNames="example" |
| 146 | ++ timeout={{ enter: 500, exit: 300 }} |
| 147 | ++ > |
| 148 | + <div onClick={() => this.handleRemove(i)}> |
| 149 | + {item} |
| 150 | + </div> |
| 151 | ++ <CSSTransition> |
| 152 | + )); |
| 153 | + |
| 154 | + return ( |
| 155 | + <div> |
| 156 | + <button onClick={this.handleAdd}>Add Item</button> |
| 157 | + <TransitionGroup> |
| 158 | + {items} |
| 159 | + </TransitionGroup> |
| 160 | + </div> |
| 161 | + ) |
| 162 | + } |
| 163 | +``` |
| 164 | + |
| 165 | +Note that we replaced `transitionName` with `classNames`. `<CSSTransition>` otherwise has essentially the same signature as `<CSSTransitionGroup>`. We also replaced `transitionEnterTimeout` and `transitionLeaveTimeout` with a single `timeout` prop with an object. |
| 166 | + |
| 167 | +> **Hint:** If your enter and exit timeouts are the same you can use the shorthand `timeout={500}`. |
| 168 | +
|
| 169 | +If we want to make this a bit more encapsulated, we can wrap our `<CSSTransition>` into a separate component for reuse later: |
| 170 | + |
| 171 | +```js |
| 172 | +const FadeTransition = (props) => ( |
| 173 | + <CSSTransition |
| 174 | + {...props} |
| 175 | + classNames="example" |
| 176 | + timeout={{ enter: 500, exit: 300 }} |
| 177 | + /> |
| 178 | +); |
| 179 | +``` |
| 180 | + |
| 181 | +We can then use it like: |
| 182 | + |
| 183 | +```diff |
| 184 | + render() { |
| 185 | + const items = this.state.items.map((item, i) => ( |
| 186 | +- <CSSTransition |
| 187 | +- key={item} |
| 188 | +- classNames="example" |
| 189 | +- timeout={{ enter: 500, exit: 300 }} |
| 190 | +- > |
| 191 | ++ <FadeTransition> |
| 192 | + <div onClick={() => this.handleRemove(i)}> |
| 193 | + {item} |
| 194 | + </div> |
| 195 | +- <CSSTransition> |
| 196 | ++ </FadeTransition> |
| 197 | + )); |
| 198 | + |
| 199 | + return ( |
| 200 | + <div> |
| 201 | + <button onClick={this.handleAdd}>Add Item</button> |
| 202 | + <TransitionGroup> |
| 203 | + {items} |
| 204 | + </TransitionGroup> |
| 205 | + </div> |
| 206 | + ) |
| 207 | + } |
| 208 | +``` |
| 209 | + |
| 210 | +> **Hey!** You may not need `<CSSTransition>` at all! The lower level `<Transition>` component is very flexible and may be easier to work with for simpler or more custom cases. Check out how we migrated [React-Bootstrap](https://react-bootstrap.github.io/)'s simple transitions to v2 for the [`<Collapse>`](https://github.com/react-bootstrap/react-bootstrap/pull/2676/files#diff-4f938f648d04d4859be417d6590ca7c4) and [`<Fade>`](https://github.com/react-bootstrap/react-bootstrap/pull/2676/files#diff-8f766132cbd9f8de55ee05d63d75abd8) components. |
| 211 | +
|
| 212 | + |
| 213 | +## Wrapping `<Transition>` Components |
| 214 | + |
| 215 | +The old `<TransitionGroup>` component managed transitions through custom static lifecycle methods on its children. In v2 we removed that API in favor of requiring that `<TransitionGroup>` be used with a `<Transition>` component, and using traditional prop passing to communicate between the two. |
| 216 | + |
| 217 | +This means that `<TransitionGroup>`s injects their children with `<Transition>`-specific props that _must_ be passed through to the `<Transition>` component for the transition to work. |
| 218 | + |
| 219 | +```js |
| 220 | +const MyTransition = ({ children: child, ...props }) => ( |
| 221 | + // NOTICE THE SPREAD! THIS IS REQUIRED! |
| 222 | + <Transition {...props}> |
| 223 | + {transitionState => React.cloneElement(child, { |
| 224 | + style: getStyleForTransitionState(transitionState) |
| 225 | + })} |
| 226 | + </Transition> |
| 227 | +); |
| 228 | + |
| 229 | +const MyList = () => ( |
| 230 | + <TransitionGroup> |
| 231 | + {items.map(item => ( |
| 232 | + <MyTransition>{item}</MyTransition> |
| 233 | + )} |
| 234 | + </TransitionGroup> |
| 235 | +); |
| 236 | +``` |
| 237 | +
|
| 238 | +Note how `<MyTransition>` passes all props other than its own to `<Transition>`. |
| 239 | +
|
| 240 | +
|
| 241 | +## Lifecycle Callbacks |
| 242 | +
|
| 243 | +As noted, child lifecycle methods have been removed. If you do need to do some work when the `<Transition>` changes from one state to another, use the lifecycle callback props. |
| 244 | +
|
| 245 | +```js |
| 246 | +<Transition |
| 247 | + {...props} |
| 248 | + onEnter={handleEnter} |
| 249 | + onEntering={handleEntering} |
| 250 | + onEntered={handleEntered} |
| 251 | + onExit={handleExit} |
| 252 | + onExiting={handleExiting} |
| 253 | + onExited={handleExited} |
| 254 | +/> |
| 255 | +``` |
| 256 | +
|
| 257 | +Each callback is called with the DOM node of the transition component. Note also that there are now _three_ states per enter/exit transition instead of the original two. See the [full documentation](https://reactcommunity.org/react-transition-group/#Transition) for more details. |
0 commit comments