nicolasdelfino / react-metro

A lightweight engine to animate dom elements as they mount or unmount

A tiny configurable wrapper for animating dom elements as they mount or unmount

• Optional hooks for binding to mount / unmount sequence complete.
• Comes with a simple fade animation but everything can be overriden by providing a custom animationsMap
• 3.3KB minimized / gzipped

Codesandbox demo

Medium

Introducing React Metro

Important note:

1.9.1 uses custom tweener MetroTween.js, list of supported easing equations in docs.

Usage

Install

npm install react-metro

Import

import Metro from "react-metro";

Metro.sequence - animate multiple objects:

Create a sequence, map it:

// in method renderMetroComponents:

// mount / unmount
if (!this.state.showMetroComponents) {
  return null;
}

const data = ["cat", "dog"];

return Metro.sequence(
  data,
  animationsMap, // optional
  defaultAnimation // optional
).map(data => {
  return (
    <Metro.animation
      {...data}
      wrapperType="div" // optional ul or whatever, defaults to div
      onClick={this.onClick.bind(this)} // optional
      enableClickDuringAnimation //optional, boolean (default false)
      onMount={this.onMountComplete.bind(this)} // optional
      onUnmount={this.onUnmountComplete.bind(this)} // optional
    >
      {" "}
      // optional
      <YourComponent {...data.content} />
    </Metro.animation>
  );
});

& render it:

<TransitionGroupPlus>
  {" "}
  // optional arg type="li/div/ul..."
  {this.renderMetroComponents()}
</TransitionGroupPlus>

Metro.container - single node enhancer:

renderMetroContainer() {
  if (!this.state.showContainer) {
    return null;
  }

  const props = {
    wrapperType: "div",
    enableClickDuringAnimation: true,
    onMount: this.wrapMount.bind(this),
    onUnmount: this.wrapUnmount.bind(this)
  };

  return Metro.container(
    <div>...</div>, // base node: pass in text, wrap components
    containerAnimation, // optional
    props //optional
  );
}

Metro.bindContainer:

// A wrapper for Metro.container that removes the need for having a conditional toggle in parent.
// Arguments:
// conditional property for toggling (bool), component (dom element), animation (object - optional), props (object optional)

renderLessVerboseContainer() {
  return Metro.bindContainer(bool, component, animation, props)
}

Customizing animations

// Override Metro´s default animations settings for each unique item in your items
// array, see MetroTween args further down.
// The animation settings are combined with the default animation settings, so
// you only have to specify the values you want to change.
const animationMap = [
  {
    in: {
      time: 3,
      delay: 0
    },
    out: {
      time: 1.4,
      delay: 1
    },
    willEnter: {
      from: { opacity: 0, y: 120, x: 30 },
      to: { opacity: 1, y: 0, x: 0, ease: "easeInOutExpo" }
    }
  },
  {
    out: {
      time: 1.4,
      delay: 0
    },
    willEnter: {
      from: { opacity: 0, y: 120, x: -30 },
      to: { opacity: 1, y: 0, x: 0, ease: "easeInOutExpo" }
    }
  }
];

// Metro comes with a simple, fade in / out default. This object passed
// in as the third argument in the Metro.sequence overrides the default settings.
// The override settings are combined with the built in defaults, so you only
// have to specify the values you want to change.
const defaultAnimationOverride = {
  animation: {
    out: {
      time: 0.5,
      delay: 0
    },
    in: {
      time: 1,
      delay: 0
    },
    willEnter: {
      from: { opacity: 0, y: 50 },
      to: { opacity: 1, y: 0, ease: "easeInOutQuad" }
    },
    willLeave: {
      from: {
        opacity: 1,
        y: 0
      },
      to: { opacity: 0, y: 50, ease: "easeInOutQuad" }
    }
  }
};

MetroTween

MetroTween is Metro's new tween engine that replaces GSAP TweenMax. It's 100% backward compatible with everything used in the codesandbox demo.

Supported tween equations:

easeInSine;
easeOutSine;
easeInOutSine;
easeInQuad;
easeOutQuad;
easeInOutQuad;
easeInCubic;
easeOutCubic;
easeInOutCubic;
easeInQuart;
easeOutQuart;
easeInOutQuart;
easeInQuint;
easeOutQuint;
easeInOutQuint;
easeInExpo;
easeOutExpo;
easeInOutExpo;
easeInCirc;
easeOutCirc;
easeInOutCirc;
easeInBack;
easeOutBack;
easeInOutBack;

Tweenable properties

x;
y;
skewX;
skewY;
scaleX;
scaleY;
rotation;
scale;

Methods

wrapperType; // dom element, defaults to div
onClick; // receives props (original array data), array index and animating
enableClickDuringAnimation; // boolean, defaults to false
onMount; // fires when the mount sequence completes
onUnmount; // fires when the unmount sequence completes

Advanced usage

The real power of Metro shines through it's use of dynamic animationMaps.

The second demo demonstrates the concept of dynamic sequences. This is achieved by altering the sequence´s animationMap on user interaction.

We define an animatonMap to achieve the delayed entrance effect we want. Since the active animationMap is stored in our wrapper component´s local state we can replace our initial map on user interaction, thus making the animation interactive.

Even though the developer has total control of an animation through the use of custom animationMaps, we created a helper method called Metro.generateFocusMap for cases where you want to accentuate a specific item within your sequence without having to write logic.

These presets - today a total of 4: verticalDelayed, dominoForwards, dominoBackwards, dominoMulti, is something that you as a developer are more than welcome to contribute to. Ideas for upcoming presets are stuff like 'checkerBoard' / 'wave' / 'circular' etc...

Each preset should try to incorporate the focus-first logic as they are intended to accentuate a clicked component. Current api for using the method is:

const domino = Metro.generateFocusMap(
  index, //focus - index of clicked component
  6, // columns
  this.state.data.length, // length of sequence
  this.state.preset // preset - dynamic in state or put directly as string 'dominoMulti'
  duration // optional (default 1 second)
)
this.setState({animationMap: domino}) // -> do unmount logic...

Contribute

PRs

PRs are welcomed, to contribute make sure that:

• Branch name references issue number if it adresses a feature / bug fix.
• Branch has already been synced with the upstream repo and any merge-conflicts have been resolved.
• Install eslint and prettier to avoid lint issues while developing
• Use semantic release guidelines when commiting

Contributors

_{Emil Pålsson}

Issues

Please be descriptive

react-metro's Issues

react-transition-group-plus not actually required?

From reading your source it looks like it's never used so I don't think you need it to be a dependency. Also it'd be nice to know why you endorse it over react-transition-group

Ideas for Metro.generateMap (helper method for advanced animations)

Metro shines through its use of animationMaps.

To dynamically specify which item to fade out first when unmounting a list of components in a sequence one needs to hook up an animationMap to the wrapper component's local state.

Then on component click (using the onClickCallback) -> get the clicked item id and modify the map so that all items except the one clicked gets a delay of 1.

I would like to make these kinds of stuff easier for the user and would appreciate ideas on how.
Leaning towards a method like:
const map = Metro.generateMap(focusIndex, numItems, animationType)

AnimationType would be a set of animation rules created by me (hopefully us), e.g 'checkerboard', 'wave', 'dominos' etc.

Thoughts?

Add option to disable interaction with animating components

Should default to true.

Creating a wrapper component for react-metro

I want to create a generic wrapper component for animations, so I tried this:

import React, { Component } from 'react';
import Metro from 'react-metro';

export class TransitionComponent extends Component {
  props: Props;

  render() {
    const { children, show } = this.props;

    if (!show) {
      return null;
    }

    return Metro.container(
      <div>
        {children}
      </div>
    );
  }
}

And I would use it like this:

      <TransitionComponent transitionName="fade" show={props.show}>
        <MyComponent {...props} />
      </TransitionComponent>

But the animations are not being applied.

Is there something I am missing about rendering children like this?

How to unmount two components in a sequential animation?

Hi Nicolas, thanks for your API, but I got a problem as mentioned in the title and I can't figure it out with your samples. Could you tell me how to do this? Thanks.

Remove GSAP dependency

Tweenmax / GSAP are huge in size, write own tweener.

Improved examples

Just stumbled upon this and really stoked to include this with some of the projects I am currently working on.

Just thought I would pass along a suggestion and get your thoughts about the current example as it seems a bit over-whelming and all squished into one. Curious if you would entertain abstracting the features of this library into smaller bit size features? Possibly breaking each feature into mini app for scene demo, basic demo, container demo, and another one for advanced demo? Just seems that the current example give you the kitchen sink along with the whole kitchen.

Cheers!

Get rid of parent local state condition to toggle

The one thing that you repeat over and over again when using Metro is the conditional toggle based on parent local state ( this.state.showThisMetroComponent && return Metro.... ).

Maybe this should be a prop passed in to Metro along with other props.

Metro - react native

Currently doesn't work with react native due to behind the scenes divs in wrapping component.
Today we have wrapperType arg that replaces the outmost top component as the specified type passed in (div / ul / li ) and so on. But it doesn't affect sister nodes.

Thinking there are three options: one could be a setting you could set before using Metro - e.g Metro.native(true), second option could be on sequence level & third option would be wrapping div to View. Either way the solution should replace all instances throughout Metro.