react-motion

What is react-motion?

react-motion is a popular library for creating animations in React applications. It leverages the physics-based animation approach to create smooth and natural transitions. The library is highly flexible and allows developers to animate various properties of their components with ease.

What are react-motion's main functionalities?

Basic Animation

This example demonstrates a basic animation where a div element moves horizontally from 0 to 100 pixels using the spring function.

```jsx
import React from 'react';
import { Motion, spring } from 'react-motion';

const BasicAnimation = () => (
  <Motion defaultStyle={{ x: 0 }} style={{ x: spring(100) }}>
    {style => <div style={{ transform: `translateX(${style.x}px)` }}>Hello World</div>}
  </Motion>
);

export default BasicAnimation;
```

Staggered Motion

This example shows how to create a staggered animation where multiple items move one after another, creating a cascading effect.

```jsx
import React from 'react';
import { StaggeredMotion, spring } from 'react-motion';

const StaggeredAnimation = () => (
  <StaggeredMotion
    defaultStyles={[{ x: 0 }, { x: 0 }, { x: 0 }]}
    styles={prevInterpolatedStyles => prevInterpolatedStyles.map((_, i) => {
      return i === 0
        ? { x: spring(100) }
        : { x: spring(prevInterpolatedStyles[i - 1].x) };
    })}
  >
    {interpolatingStyles => (
      <div>
        {interpolatingStyles.map((style, i) => (
          <div key={i} style={{ transform: `translateX(${style.x}px)` }}>Item {i}</div>
        ))}
      </div>
    )}
  </StaggeredMotion>
);

export default StaggeredAnimation;
```

Transition Motion

This example demonstrates how to use TransitionMotion to animate the addition and removal of items in a list, with smooth transitions for entering and leaving elements.

```jsx
import React from 'react';
import { TransitionMotion, spring } from 'react-motion';

class TransitionAnimation extends React.Component {
  state = { items: ['a', 'b', 'c'] };

  willEnter() {
    return { opacity: 0 };
  }

  willLeave() {
    return { opacity: spring(0) };
  }

  render() {
    return (
      <TransitionMotion
        styles={this.state.items.map(item => ({ key: item, style: { opacity: spring(1) } }))}
        willEnter={this.willEnter}
        willLeave={this.willLeave}
      >
        {interpolatedStyles => (
          <div>
            {interpolatedStyles.map(config => (
              <div key={config.key} style={{ opacity: config.style.opacity }}>{config.key}</div>
            ))}
          </div>
        )}
      </TransitionMotion>
    );
  }
}

export default TransitionAnimation;
```

Other packages similar to react-motion

react-spring

react-spring is a spring-physics based animation library that is highly flexible and performant. It provides a more modern API compared to react-motion and supports hooks, making it a popular choice for new React projects.

framer-motion

framer-motion is a powerful animation library that offers a simple and declarative API for creating animations. It supports keyframes, spring animations, and gestures, and is known for its ease of use and rich feature set.

react-transition-group

react-transition-group is a low-level animation library that provides more control over the animation lifecycle. It is often used for more complex animations where developers need fine-grained control over the transition states.

README

React-Motion

<Spring defaultValue={{val: 0}} endValue={{val: 10}}>
  {interpolated => <div>{interpolated.val}</div>}
</Spring>

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

Npm: npm install react-motion

Bower: bower install react-motion

1998 Script Tag: <script src="path/to/react-motion/build/react-motion.js"></script> (Module exposed as ReactMotion)

Or build it yourself from the repo: git clone https://github.com/chenglou/react-motion.git && npm i && npm run prerelease

For React-native, instead of require('react-motion'), do require('react-motion/native').

Check Out The Cool Demos Here.

What does this library try to solve?

My React-Europe talk

For 95% of use-cases of animating components, we don't have to resort to using hard-coded easing curves and duration. Set up a stiffness and damping for your UI element, and let the magic of physics take care of the rest. This way, you don't have to worry about the more petty questions such as "what if the item's currently animating and is a position x? How do I adjust my time and curve?". It also greatly simplifies an animation API since there's really not that much to set up.

This library also provides an alternative, more powerful API for React's TransitionGroup.

API

Sample Usage

let Demo = React.createClass({
  getInitialState() {
    return {open: false};
  },

  handleMouseDown() {
    this.setState({open: !this.state.open});
  },

  render() {
    return (
      <div>
        <button onMouseDown={this.handleMouseDown}>Toggle</button>
        <Spring defaultValue={{val: 0}} endValue={{val: this.state.open ? 400 : 0}}>
          {interpolated =>
            <div className="demo0-block" style={{
              transform: `translate3d(${interpolated.val}px, 0, 0)`,
            }} />
          }
        </Spring>
      </div>
    );
  }
});

The library exports Spring, TransitionSpring, presets and utils.

<Spring />

Exposes the props defaultValue (object or array) and endValue (object, array or a function that returns an object or an array).

Types:

• defaultValue: object | array.
• endValue: object | array | object -> (object | array).

Both values can be of an arbitrary shape (but must have the same shape. endValue must stay the same shape from one render to the next).

defaultValue is used as the first value upon mounting. Usually your endValue would differ from it, as to give the mounting animation effect.

endValue is the value you want to reach. There are 2 reserved keys for it: val and config. Say your initial data structure looks so:

{size: 10, top: 20}

You only want to animate size. Indicate what value/entire sub-collection you want to animate by wrapping it:

{size: {val: 10}, top: 20}

When you pass this to endValue, Spring will traverse your data structure and animate size based on the end value you provided and the speed/position. top will be kept untouched. You receive the interpolated data structure as an argument to your children function:

<Spring endValue={{size: {val: 10}, top: 20}}>
  {tweeningCollection => {
    let style = {
      width: tweeningCollection.size.val,
      height: tweeningCollection.size.val,
      top: tweeningCollection.top,
    };
    return <div style={style} />;
  }}
</Spring>

Where the value of tweeningCollection might be e.g. {size: {val: 3.578}, top: 20}.

If, instead of passing a number to val ({val: 10}), you pass an array or an object, by default Spring will interpolate every number in it.

But lots of times you don't want all the values to animate the same way. You can pass a config to specify the stiffness and the damping of the spring:

{size: {val: 10, config: [120, 17]}, top: 20}

A stiffness of 120 and damping of 17 gives the spring a slight bounce effect. The library exports a presets object that contains the commonly used stiffness and damping. See the presets section below.

You can nest val wrappers; the innermost takes priority:

{
  val: {
    size: {val: 10, config: [120, 17]},
    top: 20,
    left: 50
  },
  config: [100, 10]
}

Here, top and left will be animated with [stiffness, damping] of [100, 10], while size will use [120, 17] instead.

Sometimes you might have a data structure where you want to animate everything but one thing:

{
  val: {
    top: 20,
    left: 50,
    opacity: 1,
    itemID: 19230,
  }
}

This is wrong, since itemID would accidentally animate too. You can of course do this:

{
  top: {val: 20},
  left: {val: 50},
  opacity: {val: 1},
  itemID: 19230,
}

But this is still slightly tedious. Here's an alternative:

{
  val: {
    top: 20,
    left: 50,
    opacity: 1,
    itemID: {val: 19230, config: []},
  }
}

Explicitly setting a config of [] signals Spring not to drill down that collection and animate.

Sometime, you want to rely on the currently interpolated value to calculate endValue. E.g. (demo 1) a chat head's final position is the current position of the leading chat head. endValue can also accept a function (prevValue) => yourEndValue, where prevValue is the data you returned from the previous tick of getEndValue.

// ...Somewhere in your React class
getEndValue: function(prevValue) {
  let endValue = prevValue.val.map((_, i) => {
    // First one follows the mouse
    return i === 0 ? this.state.mousePosition : prevValue.val[i - 1];
  });
  // Have fun adjusting config to make the chat heads bounce a little more!
  return {val: endValue, config: [120, 17]};
},

// in render: <Spring endValue={this.getEndValue}></Spring>

<TransitionSpring />

Like Spring, but can take two other props: willEnter and willLeave. Throughout this section, please remember that

defaultValue: see endValue just below.

endValue: now constrained to an object (or a callback currentValue -> object) of the shape {key => yourStuff} (the data is constrained to this shape, but that doesn't mean the way you use your interpolated value has to be). When endValue differs from the current interpolated value by an added/removed key:

willEnter: a callback that's called once and is passed (keyThatEnters, correspondingValueOfKey, endValueYouJustSpecified, currentInterpolatedValue, currentSpeed). Return an object/array configuration that'll serve as the starting value of that new key. That configuration will be merged into endValue. The default value of willEnter is (key, endValue) => endValue[key]. It returns the same configuration as the one you just specified in endValue. In other words, the start and end are the same: no animation.

willLeave: a callback that's called many times and is passed (keyThatLeaves, correspondingValueOfKeyThatJustLeft, endValueYouJustSpecified, currentInterpolatedValue, currentSpeed). Return an object/array configuration (which will serve as the new endValue[keyThatLeaves] and merged into endValue). When that value is reached through the spring interpolation, the key will be actually unmounted.

Sample Usage

(See the demo files for fuller ones.)

let Demo = React.createClass({
  getInitialState() {
    return {
      blocks: {
        a: 'I am a',
        b: 'I am b',
        c: 'I am c',
      },
    };
  },

  getEndValue() {
    let blocks = this.state.blocks;
    let configs = {};
    Object.keys(blocks).forEach(key => {
      configs[key] = {
        height: {val: 50},
        opacity: {val: 1},
        text: blocks[key], // interpolate the above 2 fields only
      };
    });
    return configs;
  },

  willEnter(key) {
    return {
      height: {val: 50},
      opacity: {val: 1},
      text: this.state.blocks[key],
    };
  },

  willLeave(key, value, endValue, currentValue, currentSpeed) {
    // the key with this value is truly killed when the values reaches destination
    return {
      height: {val: 0},
      opacity: {val: 0},
      text: currentValue[key].text,
    };
  },

  handleClick(key) {
    let {...newBlocks} = this.state.blocks;
    delete newBlocks[key];
    this.setState({blocks: newBlocks});
  },

  render() {
    return (
      <TransitionSpring
        endValue={this.getEndValue()}
        willEnter={this.willEnter}
        willLeave={this.willLeave}>
        {currentValue =>
          <div>
            {Object.keys(currentValue).map(key => {
              let style = {
                height: currentValue[key].height.val,
                opacity: currentValue[key].opacity.val,
              };
              return (
                <div onClick={this.handleClick.bind(null, key)} style={style}>
                  {currentValue[key].text}
                </div>
              );
            })}
          </div>
        }
      </TransitionSpring>
    );
  }
});

presets

Some tasteful, commonly used spring presets you can plug into your endValue like so: {val: 10, config: presets.wobbly}. See here.

Little Extras

(You might not need this until later on.) Since TransitionSpring dictates endValue to be an object, manipulating keys could be a little more tedious than manipulating arrays. Here are the common scenarios' solutions:

• Insert at the beginning: {newKey: myConfigForThisKey, ...oldConfigs}.
• Insert at the end: {...oldConfigs, newKey: myConfigForThisKey}.
• Slice/splice/reverse/sort: this library exposes a utils.reorderKeys function.

Note: object keys creation order is now guaranteed by the specs, except for integer keys, which follow ascending order and should not be used with TransitionSpring (unless that behavior's what you want). Fortunately, you can just add a letter to your key to solve the integer order problem.

utils.reorderKeys(object, newKeysFunction)

newKeysFunction will receive, as arguments, the array of keys in object and should return a new array of keys (with e.g. order changed and/or keys missing). reorderKeys will then return a new object similar to object, but with the keys in the order newKeysFunction dictated.

FAQ

• How do I do staggering/chained animation where items animate in one after another? In most cases, what you want to express here is a relationship between animations, e.g. item 2 appears after item 1. Staggering/chained animation have hard-coded values and go against the spirit of a physics system. Check out demo 1; each ball follows the one in front of it, creating a natural staggering animation. The code in endValue looks roughly so:

<Spring endValue={prevValue => {
  const endValue = prevValue.val.map(
    (_, i) => i === 0 ? someMousePosition : prevValue.val[i - 1]
  );
  return {val: endValue};
}}>
  ...

First ball's destination is the mouse position. The subsequent ones' destination is the current position of the ball in front of them (technically, the previous tick's position; Doesn't matter much). The values depend on each other. No hard-coded duration/timeout here!

• My ref doesn't work in the children function. React string refs won't work:

<Spring endValue={...}>
  {currentValue => <div ref="stuff" />}
</Spring>

This is how React works. Here's the callback ref solution.