@tboyt/react-flip-toolkit v6.4.1

Comparison with other React FLIP libraries

Table of Contents

• Demos
• Quick start
  • Expanding Div (Fork on Code Sandbox)
  • List Shuffle (Fork on Code Sandbox)
• Usage with Vanilla JS or Other Frameworks Like Vue.js
  • Expanding Div (Fork on Code Sandbox)
• The Components
  • 1. Flipper
    • Basic Props
    • Advanced Props
  • 2. Flipped
    • Basic props
    • Callback props
    • Transform props
    • Advanced props
• Intermediate Tutorial
• Practical scale transitions
• Library details
• Troubleshooting
  • Problem #1: Nothing is happening
  • Problem #2: Things look weird
  • Problem #3: It's still not working
• Performance
  • 1. PureComponent
  • 2. will-change:transform

Demos

• Animated List (react-flip-move clone)
• Guitar shop
• Overly complex, nested cards example
• React-flip-toolkit logo
• Using Portals

Quick start

npm install react-flip-toolkit or yarn add react-flip-toolkit

1. Wrap your animations with a single Flipper component that has a flipKey prop that changes every time animations should happen.

2. Wrap elements that should be animated with Flipped components that have a flipId prop matching them across renders.

Expanding Div (Fork on Code Sandbox)

import React, { Component } from 'react';
import { Flipper, Flipped } from 'react-flip-toolkit';

class AnimatedSquare extends Component {
  state = { fullScreen: false };

  toggleFullScreen = () => {
    this.setState(prevState => ({
      fullScreen: !prevState.fullScreen
    }));
  };

  render() {
    return (
      <Flipper flipKey={this.state.fullScreen}>
        <Flipped flipId="square">
          <div
            className={this.state.fullScreen ? "full-screen-square" : "square"}
            onClick={this.toggleFullScreen}
          />
        </Flipped>
      </Flipper>
    );
  }
}

List Shuffle (Fork on Code Sandbox)

import React, { Component } from 'react';
import { Flipper, Flipped } from 'react-flip-toolkit';

class ListShuffler extends Component {
  state = { data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] };

  shuffle = () =>
    this.setState(({ data }) => ({
      data: shuffle(data)
    }));

  render() {
    return (
      <Flipper flipKey={this.state.data.join("")}>
        <button onClick={this.shuffle}> shuffle</button>
        <ul className="list">
          {this.state.data.map(d => (
            <Flipped key={d} flipId={d}>
              <li>{d}</li>
            </Flipped>
          ))}
        </ul>
      </Flipper>
    );
  }
}

Usage with Vanilla JS or Other Frameworks Like Vue.js

React-Flip-Toolkit exports a special file, core, that allows you to use the methods from the library imperatively, without requiring React. You could use this with vanilla JavaScript, or hook into the lifecycle events of a Vue.js component.

You can refer to the React documentation below to see what options can be passed to the Flipper class constructor as well as the addFlipped function exposed by the Flipper instance (which takes options corresponding to the Flipped component's props).

Expanding Div (Fork on Code Sandbox)

import Flipper from "react-flip-toolkit/es/core";
// or if you're using commonjs imports: import Flipper from "react-flip-toolkit/lib/core
const container = document.querySelector(".container");
const square = document.querySelector(".square");
const innerSquare = document.querySelector(".inner-square");

// the config options for the Flipper class are the same
// as the allowed props for the Flipper component
const flipper = new Flipper({ element: container });

// add flipped children to the parent
// options are the same as the props
// for the Flipped component
flipper.addFlipped({
  element: square,
  flipId: "square",
  onStart: () => console.log("animation started!"),
  onComplete: () => console.log("animation completed!")
});

// to add an inverted child, use this method with
// a reference to the parent element
flipper.addInverted({
  element: innerSquare,
  parent: square
});

square.addEventListener("click", () => {
  // record positions before they change
  flipper.recordBeforeUpdate();
  square.classList.toggle("big-square");
  // record new positions and begin animations
  flipper.onUpdate();
});

The Components

1. Flipper

The parent wrapper component that contains all the elements to be animated. You'll most typically need only one of these per page.

<Flipper flipKey={someKeyThatChanges}>
  {/* children */}
</Flipper>

Basic Props

staggerConfig={{
  // the "default" config will apply to staggered elements without explicit keys
      default: {
        // default direction is forwards
        reverse: true,
        // default is .1, 0 < n < 1
        speed: .5
      },
  // this will apply to Flipped elements with the prop stagger='namedStagger'
    namedStagger : { speed: .2 }
  }}

Advanced Props

   handleEnterUpdateDelete({
     // this func applies an opacity of 0 to entering elements so
     // they can be faded in - it should be called immediately
     hideEnteringElements,
     // calls `onAppear` for all entering elements
     animateEnteringElements,
     //calls `onExit` for all exiting elements
     // returns a promise that resolves when all elements have exited
     animateExitingElements,
     // the main event: `FLIP` animations for updating elements
     // this also returns a promise that resolves when
     // animations have completed
     animateFlippedElements
   })

2. Flipped

Wraps an element that should be animated.

E.g. in one component you can have

<Flipped flipId="coolDiv">
  <div className="small" />
</Flipped>

and in another component somewhere else you can have

<Flipped flipId="coolDiv">
  <div className="big" />
</Flipped>

and they will be tweened by react-flip-toolkit.

The Flipped component produces no markup, it simply passes some props down to its wrapped child.

Wrapping a React Component

If you want to wrap a React component rather than a JSX element like a div, you can provide a render prop and then apply the flippedProps directly to the wrapped element in your component:

<Flipped>
 {flippedProps => <MyCoolComponent flippedProps={flippedProps} />}
</Flipped>

const MyCoolComponent = ({ flippedProps }) => (<div {...flippedProps}/>)

You can also simply provide a regular React component as long as that component spreads unrecognized props directly onto the wrapped element (this technique works well for wrapping styled components):

<Flipped>
 <MyCoolComponent />
</Flipped>

const MyCoolComponent = ({ knownProp, ...rest }) => (<div {...rest}/>)

Basic props

Callback props

The above animation uses onAppear and onExit callbacks for fade-in and fade-out animations.

Transform props

By default the FLIP-ped elements' translate, scale, and opacity properties are all transformed. However, certain effects require more control so if you specify any of these props, only the specified attribute(s) will be tweened:

Advanced props

Functions to control when FLIP happens

Intermediate Tutorial

Learn how to easily set up an elegant animation with this step-by-step tutorial.

Practical scale transitions

Some other FLIP libraries just allow you to animate position changes, but things get more interesting once you can animate scale changes as well.

view on Codepen

The problem with scale animations has to do with children — if you scale a div up 2x, you will warp any children it has by scaling them up too, creating a weird-looking animation. That's why this library allows you to wrap the child with a Flipped component that has an inverseFlipId to counteract the transforms of the parent:

<Flipped flipId={id}>
  <div>
    <Flipped inverseFlipId={id} scale>
      <div>some text that will not be warped</div>
    </Flipped>
  </div>
</Flipped>

By default, both the scale and the translation transforms of the parent will be counteracted (this allows children components to make their own FLIP animations without being affected by the parent). But for many use cases, you'll want to additionally specify the scale prop to limit the adjustment to the scale and allow the positioning to move with the parent.

The DOM element with the inverse transform should lie flush against its parent container for the most seamless animation.

That means any layout styles — padding, flexbox, etc—should be applied to the inverted container (the element wrapped with a Flipped component with an inverseFlipId) rather than the parent Flipped container.

Library details

• Requires React 16+
• Tested in latest Chrome, Firefox, Safari, Edge, and IE 11.
• For IE11 compatability, make sure you're polyfilling the window.Promise object.
• Uses Rematrix for matrix calculations and a simplified fork of Rebound for spring animations

Troubleshooting

Problem #1: Nothing is happening

• Make sure you're updating the flipKey attribute in the Flipper component whenever an animation should happen.
• If one of your Flipped components is wrapping another React component rather than a DOM element, use a render prop to get the Flipped props and pass down to the necessary DOM element.

Problem #2: Things look weird

• At any point, there can only be one element with a specified flipId on the page. If there are multiple Flipped elements on the page with the same id, the animation will break. Check to make sure all flipIds are unique.
• Make sure you are animating the element you want to animate and not, for instance, a wrapper div. If you are animating an inline element like some text, but have wrapped it in a div, you're actually animating the div, which might have a much wider width that you'd expect at certain points, which will throw off the animation. Check to see if you need to add an inline-block style to the animated element.
• Make sure you don't have any competing CSS transitions on the element in question.

Problem #3: It's still not working

• Try out the debug prop. If you still can't figure out what's going wrong, you can add the the debug prop directly on your Flipper component to pause transitions at the beginning.
• If you think something might actually be broken, or are completely stuck, feel free to make an issue.

Performance

React-flip-toolkit does a lot of work under the hood to try to maximize the performance of your animations — for instance, off-screen elements won't be animated, and style updates are batched to prevent layout thrashing. However, if you are building particularly complex animations—ones that involve dozens of elements or large images— there are some additional strategies you can use to ensure performant animations.

1. PureComponent

When you trigger a complex FLIP animation with react-flip-toolkit, React could be spending vital milliseconds doing unnecessary reconciliation work before allowing the animation to start. If you notice a slight delay between when the animation is triggered, and when it begins, this is probably the culprit. To short-circuit this possibly unnecessary work, try using PureComponent for your animated elements, and seeing if you can refactor your code to minimize prop updates to animated children when an animation is about to occur.

For example, in a hypothetical UI where you are animating the positions of several cards at once, you might want to update a Card component that looks like this:

import React, { Component } from 'react'

class Card extends Component {
  render() {
    return (
        <Flipped flipId={this.props.id}>
          <div>
          {/* card content goes here */ }
          </div>
        </Flipped>
    )
  }
}

to this:

import React, { PureComponent } from 'react'

class Card extends PureComponent {
 // everything  else is the same
}

Remember to always provide key props as appropriate to your elements, and check the React docs for some caveats on when to not use PureComponent. But if you have complex animations with noticeable lag, think about giving PureComponent a try.

2. will-change:transform

.image {
  will-change:transform;
}

This somewhat mysterious CSS property tells the browser to anticipate changes to an element. It should be used with caution, because it can increase browser resource usage. If you are animating images (svg, jpg, etc), I would recommend trying it out and seeing if it increases the performance of the animation. In my tests, when animating one or two large images, will-change:transform increased animation frame rate. However, trying to apply it to too many components at once (20+) actually decreased performance considerably.