A library for animating React – Facebook programmers (unofficial)

import {Motion, spring} from 'react-motion';
// In your render...

  {value => 
      

       {value.x}
      
}

Animate a counter from 0 to 10. For more advanced usage, see below.

Install

• Npm: npm install --save react-motion

• Bower: do not install with bower install react-motion, it won’t work. Use bower install --save https://npmcdn.com/react-motion/bower.zip. Or in bower.json:

{
  "dependencies": {
    "react-motion": "https://npmcdn.com/react-motion/bower.zip"
  }
}

then include as

(Module exposed as `ReactMotion`)

For React-native: Previous React-Motion V0.3.* Supported a dedicated build for RN, This library should Just Work under the new React-native 0.18+.

Try things yourself

git clone https://github.com/chenglou/react-motion.git
cd react-motion
npm install

Demos

Check the wiki for more!

What does this library try to solve?

My React-Europe talk

API

Coming from 0.3.* to 0.4.0? Here’s the upgrade guide.

Helpers

– spring: (val: number, config? : SpringHelperConfig) => OpaqueConfig

– Presets for {stiffness, damping}

Commonly used spring configurations used like so: spring(10, presets.wobbly) or spring(20, {… Presets. Gentle, precision: 0.1}). See here.

Usage

  {interpolatingStyle => 
      
}

Props

– style: Style

Required. The Style type is an object that maps to either a number or an OpaqueConfig returned by spring() above. Must keep the same keys throughout component’s existence. The meaning of the values:

• an OpaqueConfig returned from spring(x): interpolate to x.
• a number x: jump to x, do not interpolate.

– defaultStyle? : PlainStyle

– children: (interpolatedStyle: PlainStyle) => ReactElement

Required function.

• interpolatedStyle: the interpolated style object passed back to you. E.g. if you gave style={{x: spring(10), y: Spring (20)}}, you’ll receive as interpolatedStyle, at a certain time, {x: interpolatedStyle, y: interpolatedStyle 12.1}, which you can then apply on your div or something else.

• Return: must return one React element to render.

Usage

 prevInterpolatedStyles.map((_, i) => {
    return i === 0
      ? {h: spring(100)}
      : {h: spring(prevInterpolatedStyles[i - 1].h)}
  })}>
  {interpolatingStyles =>
    
      

      {interpolatingStyles.map((style, i) =>
        
      

       )
      
}}

Aka “the current spring’s destination value is the interpolating value of the previous spring”. Imagine a spring dragging another. Physics, it works!

Props

– styles: (previousInterpolatedStyles: ?Array) => Array</h5> <p>Required <strong>function</strong>. <strong>Don’t forget the “s”</strong>!</p> <ul> <li><p><code>previousInterpolatedStyles</code>: the previously interpolating (array of) styles (<code>undefined</code> at first render, unless <code>defaultStyles</code> is provided).</p></li> <li><p>Return: must return an array of <code>Style</code>s containing the destination values, e.g. <code>[{x: spring(10)}, {x: spring(20)}]</code>.</p></li> </ul> <h5><a href=”https://github.com/chenglou/react-motion#–defaultstyles-arrayplainstyle”><svg height=”16″ width=”16″><path/></svg></a>- defaultStyles?: Array<PlainStyle></h5> <p>Optional. Similar to <code>Motion</code>’s <code>defaultStyle</code>, but an array of them.</p> <h5><a href=”https://github.com/chenglou/react-motion#–children-interpolatedstyles-arrayplainstyle–reactelement”><svg height=”16″ width=”16″><path/></svg></a>- children: (interpolatedStyles: Array<PlainStyle>) => ReactElement</h5> <p>Required <strong>function</strong>. Similar to <code>Motion</code>’s <code>children</code>, but accepts the array of interpolated styles instead, e.g. <code>[{x: 5}, {x: 6.4}, {x: 8.1}]</code></p> <h3><a href=”https://github.com/chenglou/react-motion#transitionmotion-“><svg height=”16″ width=”16″><path/></svg></a><TransitionMotion /></h3> <p><strong>Helps you to do mounting and unmounting animation</strong>.</p> <h4><a href=”https://github.com/chenglou/react-motion#usage-2″><svg height=”16″ width=”16″><path/></svg></a>Usage</h4> <p>You have items <code>a</code>, <code>b</code>, <code>c</code>, with their respective style configuration, given to <code>TransitionMotion</code>’s <code>styles</code>. In its <code>children</code> function, you’re passed the three interpolated styles as params; you map over them and produce three components. All is good.</p> <p>During next render, you give only <code>a</code> and <code>b</code>, indicating that you want <code>c</code> gone, but that you’d like to animate it reaching value <code>0</code>, before killing it for good.</p> <p>Fortunately, <code>TransitionMotion</code> has kept <code>c</code> around and still passes it into the <code>children</code> function param. So when you’re mapping over these three interpolated styles, you’re still producing three components. It’ll keep interpolating, while checking <code>c</code>’s current value at every frame. Once <code>c</code> reaches the specified <code>0</code>, <code>TransitionMotion</code> will remove it for good (from the interpolated styles passed to your <code>children</code> function).</p> <p>This time, when mapping through the two remaining interpolated styles, you’ll produce only two components. <code>c</code> is gone for real.</p> <div><pre>const Demo = React.createClass({ getInitialState() { return { items: [{key: ‘a’, size: 10}, {key: ‘b’, size: 20}, {key: ‘c’, size: 30}], }; }, componentDidMount() { this.setState({ items: [{key: ‘a’, size: 10}, {key: ‘b’, size: 20}], // remove c. }); }, willLeave() { // triggered when c’s gone. Keeping c until its width/height reach 0. return {width: spring(0), height: spring(0)}; }, render() { return ( <TransitionMotion willLeave={this.willLeave} styles={this.state.items.map(item => ({ key: item.key, style: {width: item.size, height: item.size}, }))}> {interpolatedStyles => // first render: a, b, c. Second: still a, b, c! Only last one’s a, b. <div></div> {interpolatedStyles.map(config => { return <div key=”{config.key}” style=”{{…config.style,” border:=”” ‘1px=”” solid’}}=””></div> })} } </TransitionMotion> ); }, });</pre></div> <h4><a href=”https://github.com/chenglou/react-motion#props-2″><svg height=”16″ width=”16″><path/></svg></a>Props</h4> <p>First, two type definitions to ease the comprehension.</p> <ul> <li><p><code>TransitionStyle</code>: an object of the format <code>{key: string, data?: any, style: Style}</code>.</p> <ul> <li><p><code>key</code>: required. The ID that <code>TransitionMotion</code> uses to track which configuration is which across renders, even when things are reordered. Typically reused as the component <code>key</code> when you map over the interpolated styles.</p></li> <li><p><code>data</code>: optional. Anything you’d like to carry along. This is so that when the previous section example’s <code>c</code> disappears, you still get to access <code>c</code>’s related data, such as the text to display along with it.</p></li> <li><p><code>style</code>: required. The actual starting style configuration, similar to what you provide for <code>Motion</code>’s <code>style</code>. Maps keys to either a number or an <code>OpaqueConfig</code> returned by <code>spring()</code>.</p></li> </ul></li> <li><p><code>TransitionPlainStyle</code>: similar to above, except the <code>style</code> field’s value is of type <code>PlainStyle</code>, aka an object that maps to numbers.</p></li> </ul> <h5><a href=”https://github.com/chenglou/react-motion#–styles-arraytransitionstyle–previousinterpolatedstyles-arraytransitionplainstyle–arraytransitionstyle”><svg height=”16″ width=”16″><path/></svg></a>- styles: Array<TransitionStyle> | (previousInterpolatedStyles: ?Array<TransitionPlainStyle>) => Array<TransitionStyle></h5> <p>Required. Accepts either:</p> <ul> <li><p>an array of <code>TransitionStyle</code> configs, e.g. <code>[{key: ‘a’, style: {x: spring(0)}}, {key: ‘b’, style: {x: spring(10)}}]</code>.</p></li> <li><p>a function similar to <code>StaggeredMotion</code>, taking the previously interpolating styles (<code>undefined</code> at first call, unless <code>defaultStyles</code> is provided), and returning the previously mentioned array of configs. <strong>You can do staggered mounting animation with this</strong>.</p></li> </ul> <h5><a href=”https://github.com/chenglou/react-motion#–defaultstyles-arraytransitionplainstyle”><svg height=”16″ width=”16″><path/></svg></a>- defaultStyles?: Array<TransitionPlainStyle></h5> <p>Optional. Similar to the other components’ <code>defaultStyle</code>/<code>defaultStyles</code>.</p> <h5><a href=”https://github.com/chenglou/react-motion#–children-interpolatedstyles-arraytransitionplainstyle–reactelement”><svg height=”16″ width=”16″><path/></svg></a>- children: (interpolatedStyles: Array<TransitionPlainStyle>) => ReactElement</h5> <p>Required <strong>function</strong>. Similar to other two components’ <code>children</code>. Receive back an array similar to what you provided for <code>defaultStyles</code>, only that each <code>style</code> object’s number value represent the currently interpolating value.</p> <h5><a href=”https://github.com/chenglou/react-motion#–willleave-stylethatleft-transitionstyle–style”><svg height=”16″ width=”16″><path/></svg></a>- willLeave?: (styleThatLeft: TransitionStyle) => ?Style</h5> <p>Optional. Defaults to <code>() => null</code>. <strong>The magic sauce property</strong>.</p> <ul> <li><p><code>styleThatLeft</code>: the e.g. <code>{key: …, data: …, value: …}</code> object from the <code>styles</code> array, identified by <code>key</code>, that was present during a previous render, and that is now absent, thus triggering the call to <code>willLeave</code>.</p></li> <li><p>Return: <code>null</code> to indicate you want the <code>TransitionStyle</code> gone immediately. A <code>Style</code> object to indicate you want to reach transition to the specified value(s) before killing the <code>TransitionStyle</code>.</p></li> </ul> <h5><a href=”https://github.com/chenglou/react-motion#–willenter-stylethatentered-transitionstyle–plainstyle”><svg height=”16″ width=”16″><path/></svg></a>- willEnter?: (styleThatEntered: TransitionStyle) => PlainStyle</h5> <p>Optional. Defaults to <code>styleThatEntered => stripStyle(styleThatEntered.style)</code>. Where <code>stripStyle</code> turns <code>{x: spring(10), y: spring(20)}</code> into <code>{x: 10, y: 20}</code>.</p> <ul> <li><p><code>styleThatEntered</code>: similar to <code>willLeave</code>’s, except the <code>TransitionStyle</code> represents the object whose <code>key</code> value was absent during the last <code>render</code>, and that is now present.</p></li> <li><p>Return: a <code>defaultStyle</code>-like <code>PlainStyle</code> configuration, e.g. <code>{x: 0, y: 0}</code>, that serves as the starting values of the animation. Under this light, the default provided means “a style config that has the same starting values as the destination values”.</p></li> </ul> <p><strong>Note</strong> that <code>willEnter</code> and <code>defaultStyles</code> serve different purposes. <code>willEnter</code> only triggers when a previously inexistent <code>TransitionStyle</code> inside <code>styles</code> comes into the new render.</p> <h2><a href=”https://github.com/chenglou/react-motion#faq”><svg height=”16″ width=”16″><path/></svg></a>FAQ</h2> <ul> <li>How do I set the duration of my animation?</li> </ul> <p><a href=”https://twitter.com/andy_matuschak/status/566736015188963328″>Hard-coded duration goes against fluid interfaces</a>. If your animation is interrupted mid-way, you’d get a weird completion animation if you hard-coded the time. That being said, in the demo section there’s a great <a href=”http://chenglou.github.io/react-motion/demos/demo5-spring-parameters-chooser”>Spring Parameters Chooser</a> for you to have a feel of what spring is appropriate, rather than guessing a duration in the dark.</p> <ul> <li>How do I unmount the <code>TransitionMotion</code> container itself?</li> </ul> <p>You don’t. Unless you put it in another <code>TransitionMotion</code>…</p> <ul> <li>How do I do staggering/chained animation where items animate in one after another?</li> </ul> <p>See <a href=”https://github.com/chenglou/react-motion#staggeredmotion-“><code>StaggeredMotion</code></a></p> <ul> <li>My <code>ref</code> doesn’t work in the children function.</li> </ul> <p>React string refs won’t work:</p> <div><pre><Motion style={…}>{currentValue => <div ref=”stuff”></div>}</Motion></pre></div> <p>This is how React works. Here’s the <a href=”https://facebook.github.io/react/docs/more-about-refs.html#the-ref-callback-attribute”>callback ref solution</a>.</p> </article> </div>