react-flip-toolkit

7.2.4 verified Sat Apr 25 auth: no javascript

A configurable FLIP animation library for React, providing smooth and performant transitions for element position, scale, and opacity changes. Current stable version 7.2.4, released under MIT license, with a release cadence of minor updates quarterly and patches as needed. Key differentiators: supports spring-based animations, stagger effects, nested scale transforms without warping children, and works with frameworks other than React via the flip-toolkit package. Ships TypeScript types. Minimal bundle size (~5KB gzipped).

Common errors

error Module not found: Can't resolve 'react-flip-toolkit' ↓

cause Missing installation or wrong import path.

fix

Run 'npm install react-flip-toolkit' or 'yarn add react-flip-toolkit'. Ensure import is from 'react-flip-toolkit'.

error Attempted import error: 'Flipper' is not exported from 'react-flip-toolkit' (imported as Flipper) ↓

cause Using incorrect import syntax or out-of-date version.

fix

Use named import: import { Flipper } from 'react-flip-toolkit'. Ensure package version is ^7.0.0.

error TypeError: Cannot read properties of undefined (reading 'current') ↓

cause Flipped component used without a prop for ref; or the element is not a DOM node.

fix

Wrap the element inside Flipped with a forwardRef component or directly use a DOM element. If using a functional component, use React.forwardRef.

error 'flipId' of '0' is being ignored ↓

cause A falsy value (like 0) was used as flipId, which got ignored in older versions.

fix

Upgrade to v7.0.13 or later, or use a non-zero string/number as flipId.

Warnings

breaking v7.0.0 changed the internal architecture and separated flip-toolkit package; react-flip-toolkit now depends on flip-toolkit. ↓

fix Upgrade to v7+ and ensure you import from 'react-flip-toolkit' directly.

breaking v7.2.0 introduced modern exports that broke type resolutions. v7.2.4 removed modern exports, defaulting to ESM. ↓

fix Upgrade to v7.2.4 or later. If you were using modern exports, switch to ESM imports.

deprecated The old default export 'ReactFlipToolkit' is deprecated. Use named exports instead. ↓

fix Replace default import with named imports: import { Flipper, Flipped } from 'react-flip-toolkit'.

gotcha Flipper's flipKey prop must change for animations to trigger. If it doesn't change, no FLIP animation will occur. ↓

fix Ensure the flipKey prop is updated (e.g., a new string or number) when the layout changes.

gotcha Flipped components require a unique flipId prop across all Flipped children. Duplicate flipIds may cause unpredictable behavior. ↓

fix Use unique flipId values, typically the same as the React key prop.

gotcha Animation of elements with zero height (e.g., display: none) may not work correctly in some versions. Fixed in v7.0.13. ↓

fix Upgrade to v7.0.13 or later.

gotcha The onComplete callback is not called when animation is cancelled (e.g., component unmounts). Fixed in v7.0.6. ↓

fix Upgrade to v7.0.6 or later.

Install

npm install react-flip-toolkit

yarn add react-flip-toolkit

pnpm add react-flip-toolkit

Imports

Flipper
wrong
```
const Flipper = require('react-flip-toolkit').Flipper
```
correct
```
import { Flipper } from 'react-flip-toolkit'
```
ESM-only since v7.2.4 (defaults to ESM exports). Use import syntax. For CJS, use dynamic import or check package exports.

Flipped

wrong

import * as Flip from 'react-flip-toolkit'

correct

import { Flipped } from 'react-flip-toolkit'

Named export, not default. Avoid star imports.

spring

wrong

import spring from 'react-flip-toolkit'

correct

import { spring } from 'react-flip-toolkit'

Named export, not default. Has been available since v7.

Flipper (type)
```
import type { Flipper } from 'react-flip-toolkit'
```
TypeScript users: use import type for type-only imports, but the library ships types so you can also use regular import.

Quickstart

Shows a basic list shuffle animation using Flipper and Flipped components. The flipKey prop triggers animation when items change order.

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

function List() {
  const [items, setItems] = useState(['a', 'b', 'c', 'd', 'e']);
  const shuffle = () => setItems(prev => {
    const arr = [...prev];
    for (let i = arr.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [arr[i], arr[j]] = [arr[j], arr[i]];
    }
    return arr;
  });
  return (
    <div>
      <button onClick={shuffle}>Shuffle</button>
      <Flipper flipKey={items.join('')}>
        <ul>
          {items.map(item => (
            <Flipped key={item} flipId={item}>
              <li>{item}</li>
            </Flipped>
          ))}
        </ul>
      </Flipper>
    </div>
  );
}

export default List;