Home

Awesome

<div style="text-align:center;"> <a href="https://github.com/sghall/react-move" target="\_parent"><img src="https://user-images.githubusercontent.com/4615775/86074106-161b9f80-ba3a-11ea-84dd-04845dd51582.png" alt="React Table Logo" style="width:450px;"/></a> </div>

React-Move

Beautiful, data-driven animations for React. Just 3.5kb (gzipped)!

Documentation and Examples

npm version npm downloads license

Features

Installation

// React ^16.3.0
npm install react-move

// React ^0.14.9 || ^15.3.0 || ^16.0.0
npm install react-move@^5.0.0

Note: The API for React Move 5.x and 6.x is exactly the same. The 5.x version just includes react-lifecycles-compat to make the library work with earlier versions of React. This adds a little to the bundle so use 6.x if you're using React 16.3+.

Upgrading from React Move 2.x and 3.x

The API for React Move has been essentially stable since the 2.0 version. The 4.0 version of React Move introduced a change that broke the hard dependency on d3-interpolate and introduced the interpolation prop. The current version of React Move will by default only do numeric interpolation and apply easing functions. If you only need to do numeric interpolation you don't need to do anything. Just upgrade and done.

To get the same interpolation found in React Move 2.x and 3.x which includes support for colors, paths and SVG transforms do this:

Install d3-interpolate:

npm install d3-interpolate

Then in your app:

import { NodeGroup } from 'react-move'
import { interpolate, interpolateTransformSvg } from 'd3-interpolate'

...
<NodeGroup
  data={this.state.data}
  keyAccessor={(d) => d.name}

  start={(data, index) => ({
    ...
  })}

  enter={(data, index) => ([ // An array
    ...
  ])}

  update={(data) => ({
    ...
  })}

  leave={() => ({
    ...
  })}

  interpolation ={(begValue, endValue, attr) => { // pass as prop
    if (attr === 'transform') {
      return interpolateTransformSvg(begValue, endValue)
    }

    return interpolate(begValue, endValue)
  }}
>
  ...children
</NodeGroup>

Demos

Documentation

The docs below are for version 6.x.x of React-Move.

Older versions:

The API for NodeGroup and Animate have not changed except for the interpolationxw prop, but if you want to refer back:

Getting Started

React Move exports just two components:

< NodeGroup />

Component Props

NameTypeDefaultDescription
<span style="color: #31a148">data *</span>arrayAn array. The data prop is treated as immutable so the nodes will only update if prev.data !== next.data.
<span style="color: #31a148">keyAccessor *</span>functionFunction that returns a string key given the data and its index. Used to track which nodes are entering, updating and leaving.
interpolationfunctionnumericA function that returns an interpolator given the begin value, end value, attr and namespace. Defaults to numeric interpolation. See docs for more.
<span style="color: #31a148">start *</span>functionA function that returns the starting state. The function is passed the data and index and must return an object.
enterfunction() => {}A function that returns an object or array of objects describing how the state should transform on enter. The function is passed the data and index.
updatefunction() => {}A function that returns an object or array of objects describing how the state should transform on update. The function is passed the data and index.
leavefunction() => {}A function that returns an object or array of objects describing how the state should transform on leave. The function is passed the data and index.
<span style="color: #31a148">children *</span>functionA function that receives an array of nodes.

< Animate />

Component Props

NameTypeDefaultDescription
showbooltrueBoolean value that determines if the child should be rendered or not.
interpolationfunctionnumericA function that returns an interpolator given the begin value, end value, atrr and namespace. See docs for more.
startunion:<br> func<br> object<br>An object or function that returns an obejct to be used as the starting state.
enterunion:<br> func<br> array<br> object<br>An object, array of objects, or function that returns an object or array of objects describing how the state should transform on enter.
updateunion:<br> func<br> array<br> object<br>An object, array of objects, or function that returns an object or array of objects describing how the state should transform on update. Note: although not required, in most cases it make sense to specify an update prop to handle interrupted enter and leave transitions.
leaveunion:<br> func<br> array<br> object<br>An object, array of objects, or function that returns an object or array of objects describing how the state should transform on leave.
<span style="color: #31a148">children *</span>functionA function that receives the state.

Starting state

Before looking at the components it might be good to look at starting state. You are going to be asked to define starting states for each item in your NodeGroup and Animate components. This is a key concept and probably the most error prone for developers working with React Move. The starting state for each item is always an object with string or number leaves. The leaf keys are referred to as "attrs" as in "attribute." There are also "namespaces" which are a purely organizational concept.

Two rules to live by for starting states:

Example starting state:

// GOOD
{
  attr1: 100,
  attr2: 200,
  attr3: '#dadada'
}

// BAD
{
  attr1: [100], // NO ARRAYS
  attr2: 200,
  attr3: '#dadada'
}

A more concrete example might be:

{
  opacity: 0.1,
  x: 200,
  y: 100,
  color: '#dadada'
}

You can add "namespaces" to help organize your state:

{
  attr1: 100,
  attr2: 200,
  attr3: '#ddaabb',
  namespace1: {
    attr1: 100,
    attr2: 200
  }
}

Or something like:

{
  namespace1: {
    attr1: 100,
    attr2: 200
  },
  namespace2: {
    attr1: 100,
    attr2: 200
  }
}

You might use namespaces like so:

{
  inner: {
    x: 100,
    y: 150,
    color: '#545454'
  },
  outer: {
    x: 300,
    y: 350,
    color: '#3e3e3e'
  }
}

Starting state in NodeGroup

In NodeGroup you are working with an array of items and you pass a start prop (a function) that receives the data item and its index. The start prop will be called when that data item (identified by its key) enters. Note it could leave and come back and that prop will be called again. Immediately after the starting state is set your enter transition (optional) is called allowing you to transform that state.

<NodeGroup
  data={data} // an array (required)
  keyAccessor={item => item.name} // function to get the key of each object (required)
  start={(item, index) => ({ // returns the starting state of node (required)
    ...
  })}
>
  {(nodes) => (
    ...
      {nodes.map(({ key, data, state }) => {
        ...
      })}
    ...
  )}
</NodeGroup>

Starting state in Animate

In Animate you are animating a single item and pass a start prop that is an object or a function. The start prop will be called when that the item enters. Note it could leave and come back by toggling the show prop. Immediately after the starting state is set your enter transition (optional) is called allowing you to transform that state.

<Animate
  start={{ // object or function
    ...
  }}
>
  {state => (
    ...
  )}
</Animate>

Transitioning state

You return a config object or an array of config objects in your enter, update and leave props functions for both NodeGroup and Animate. Instead of simply returning the next state these objects describe how to transform the state. Each config object can specify its own duration, delay, easing and events independently.

There are two special keys you can use: timing and events. Both are optional. Timing and events are covered in more detail below.

If you aren't transitioning anything then it wouldn't make sense to be using NodeGroup. That said, it's convenient to be able to set a key to value when a node enters, updates or leaves without transitioning. To support this you can return four different types of values to specify how you want to transform the state.

Example config object:

{
  attr1: [200],
  attr2: 300,
  attr3: ['#dadada']
  timing: { duration: 300, delay: 100 }
}

Using namespaces:

{
  attr1: [100],
  attr3: '#ddaabb',
  namespace1: {
    attr1: [300],
    attr2: 200
  },
  timing: { duration: 300, delay: 100 }
}

To have different timing for some keys use an array of config objects:

[
  {
    attr1: [200, 500],
    timing: { duration: 300, delay: 100 }
  },
  {
    attr2: 300, // this item, not wrapped in an array, will be set immediately, so which object it's in doesn't matter
    attr3: ['#dadada']
    timing: { duration: 600 }
  },
]

Example Transitions in NodeGroup

<NodeGroup
  data={this.state.data}
  keyAccessor={(d) => d.name}

  start={(data, index) => ({
    opacity: 1e-6,
    x: 1e-6,
    fill: 'green',
    width: scale.bandwidth(),
  })}

  enter={(data, index) => ({
    opacity: [0.5], // transition opacity on enter
    x: [scale(data.name)], // transition x on on enter
    timing: { duration: 1500 }, // timing for transitions
  })}

  update={(data) => ({
    ...
  })}

  leave={() => ({
    ...
  })}
>
  {(nodes) => (
    ...
  )}
</NodeGroup>

Using an array of config objects:

import { easeQuadInOut } from 'd3-ease';

...

<NodeGroup
  data={this.state.data}
  keyAccessor={(d) => d.name}

  start={(data, index) => ({
    opacity: 1e-6,
    x: 1e-6,
    fill: 'green',
    width: scale.bandwidth(),
  })}

  enter={(data, index) => ([ // An array
    {
      opacity: [0.5], // transition opacity on enter
      timing: { duration: 1000 }, // timing for transition
    },
    {
      x: [scale(data.name)], // transition x on on enter
      timing: { delay: 750, duration: 1500, ease: easeQuadInOut }, // timing for transition
    },
  ])}

  update={(data) => ({
    ...
  })}

  leave={() => ({
    ...
  })}
>
  {(nodes) => (
    ...
  )}
</NodeGroup>

Timing

If there's no timing key in your object you'll get the timing defaults. You can specify just the things you want to override on your timing key.

Here's the timing defaults...

const defaultTiming = {
  delay: 0,
  duration: 250,
  ease: easeLinear
};

For the ease key, just provide the function. You can use any easing function, like those from d3-ease...

List of ease functions exported from d3-ease

Events

You can add events on your config objects. You can pass a function that will run when the transition starts, is interrupted (an update to the data occurs) or ends.

Using Events:

{
  attr1: [100],
  attr3: '#ddaabb',
  namespace1: {
    attr1: [300],
    attr2: 200
  },
  timing: { duration: 300, delay: 100 },
  events: {
    start: () => {
      ..do stuff - use an arrow function to keep the context of the outer component
    },
    interrupt: () => {
      ..do stuff - use an arrow function to keep the context of the outer component
    },
    end: () => {
      ..do stuff - use an arrow function to keep the context of the outer component
    },
  }
}

Interpolation

You can wire your components in react-move to handle different types of interpolation using the interpolation prop in both NodeGroup and Animate. The code for interpolating strings or SVG paths can be bulky and, in many cases, it's not needed so by default components only handle numeric interpolation.

Your interpolation prop is a function that should avoid a lot of logic and computation. It will get called at high frequency when transitions fire in your components. You get the begin and end values and what the attribute name (string) is. You will also get the namespace string (less common) if you are using them in your state. See the sections on starting states and transitions for more on attrs and namespaces.

Cadillac Interpolation - Depends on d3-interpolate

To wire up a full service interpolation that will interpolate colors, paths, numbers and SVG transforms you can use a setup like this:

npm install react-move d3-interpolate

Then in your app:

import { NodeGroup, Animate } from 'react-move'
import { interpolate, interpolateTransformSvg } from 'd3-interpolate'

...
<NodeGroup
  data={this.state.data}
  keyAccessor={(d) => d.name}

  start={(data, index) => ({
    ...
  })}

  enter={(data, index) => ([ // An array
    ...
  ])}

  update={(data) => ({
    ...
  })}

  leave={() => ({
    ...
  })}

  interpolation ={(begValue, endValue, attr, namespace) => { // pass as prop
    if (attr === 'transform') {
      return interpolateTransformSvg(begValue, endValue)
    }

    return interpolate(begValue, endValue)
  }}
>
  ...children
</NodeGroup>

This setup mimics how d3.js works for selecting interpolators and will not force you to think too much about the values your are using. For example, if you use colors (in any format) they will be recognized and interpolated correctly. The interpolate function exported from d3-interpolate does a great job of guessing what you're trying to do and handles it for you but it also includes a lot of code (e.g. d3-color) that may not be needed for your project.

Numeric Interpolation Only - Default - No dependencies

To do numeric interpolation you don't need to do anything in your components. The default numeric interpolator looks like this:

// The default interpolator used in NodeGroup and Animate

const numeric = (beg, end) => {
  const a = +beg;
  const b = +end - a;

  return function(t) {
    return a + b * t;
  };
};

React-Move vs React-Motion

Contributing

We love contributions from the community! Read the contributing info here.

Run the repo locally

Scripts

Run these from the root of the repo

Go to live examples, code and docs!