npmpackage.info

react-flip-move

Effortless animation between DOM changes (eg. list reordering) using the FLIP technique.

3.0.5

4,092

MIT

JavaScript

33,038,871 2.3

Installations

npm install react-flip-move

Pull Requests

Open

1

Total

105

Closed

13

Merged

91

Issues

Open

33

Total

173

Closed

140

Releases

v3.0.3

Published on 19 Oct 2018

v3.0.2

Published on 03 Sept 2018

v3.0.1

Published on 30 Jan 2018

v3.0.0

Published on 14 Jan 2018

v2.10.2

Published on 10 Jan 2018

v2.10.1

Published on 05 Jan 2018

View all 76 releases

Developer

joshwcomeau

Developer Guide

BETA

Module System

CommonJS

Min. Node Version

Typescript Support

No

Node Version

17.1.0

NPM Version

8.1.2 Statistics

4,092 Stars

328 Commits

256 Forks

45 Watching

4 Branches

33 Contributors

Updated on 27 Nov 2024

Languages

JavaScript (97.24%)

TypeScript (2.71%)

HTML (0.05%)

Total Downloads

Cumulative downloads

Total Downloads

33,038,871

Last day

24.8%

30,168

Compared to previous day

Last week

19.5%

148,468

Compared to previous week

Last month

16.8%

572,375

Compared to previous month

Last year

-9.1%

6,680,174

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Peer Dependencies

react react-dom

Dev Dependencies

@storybook/react @types/react babel babel-core babel-eslint babel-loader babel-plugin-add-module-exports babel-plugin-external-helpers babel-plugin-istanbul babel-plugin-transform-decorators-legacy babel-plugin-transform-object-assign babel-preset-env babel-preset-flow babel-preset-react babel-preset-stage-0 chai create-react-class cross-env enzyme enzyme-adapter-react-16 eslint eslint-config-airbnb eslint-config-prettier eslint-plugin-bdd eslint-plugin-flowtype eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-prettier eslint-plugin-react eslint-plugin-sort-class-members flow-bin flow-coverage-report husky karma karma-chai karma-chrome-launcher karma-coverage karma-mocha karma-sinon karma-sinon-chai karma-sourcemap-loader karma-webpack lodash mocha preact preact-compat prettier prop-types react react-dom react-test-renderer rollup rollup-plugin-babel rollup-plugin-replace rollup-plugin-uglify sinon sinon-chai styled-components tslint typescript webpack

Versions

React Flip Move

This module was built to tackle the common but arduous problem of animating a list of items when the list's order changes.

CSS transitions only work for CSS properties. If your list is shuffled, the items have rearranged themselves, but without the use of CSS. The DOM nodes don't know that their on-screen location has changed; from their perspective, they've been removed and inserted elsewhere in the document.

Flip Move uses the FLIP technique to work out what such a transition would look like, and fakes it using 60+ FPS hardware-accelerated CSS transforms.

Read more about how it works

Current Status

React Flip Move is looking for maintainers!

In the meantime, we'll do our best to make sure React Flip Move continues to work with new versions of React, but otherwise it isn't being actively worked on.

Because it isn't under active development, you may be interested in checking out projects like react-flip-toolkit.

Demos

Installation

Flip Move can be installed with NPM or Yarn.

1yarn add react-flip-move
2
3# Or, if not using yarn:
4npm i -S react-flip-move

A UMD build is made available for those not using JS package managers:

To use a UMD build, you can use <script> tags:

1<html>
2  <body>
3    <script src="https://unpkg.com/react-flip-move/dist/react-flip-move.js"></script>
4    <script>
5      // Will be available under the global 'FlipMove'.
6    </script>
7  </body>
8</html>

Features

Flip Move was inspired by Ryan Florence's awesome Magic Move, and offers:

Exclusive use of hardware-accelerated CSS properties (transform: translate) instead of positioning properties (top, left). Read why this matters.
Full support for enter/exit animations, including some spiffy presets, that all leverage hardware-accelerated CSS properties.
Ability to 'humanize' transitions by staggering the delay and/or duration of subsequent elements.
Ability to provide onStart / onFinish callbacks.
Compatible with Preact (should work with other React-like libraries as well).
Tiny! Gzipped size is <5kb! ⚡

Quickstart

Flip Move aims to be a "plug and play" solution, without needing a lot of tinkering. In the ideal case, you can wrap the children you already have with <FlipMove>, and get animation for free:

1/**
2 * BEFORE:
3 */
4const TopArticles = ({ articles }) => (
5  {articles.map(article => (
6    <Article key={article.id} {...article} />
7  ))}
8);
9
10/**
11 * AFTER:
12 */
13import FlipMove from 'react-flip-move';
14
15const TopArticles = ({ articles }) => (
16  <FlipMove>
17    {articles.map(article => (
18      <Article key={article.id} {...article} />
19    ))}
20  </FlipMove>
21);

There are a number of options you can provide to customize Flip Move. There are also some gotchas to be aware of.

Usage with Functional Components

Functional components do not have a ref, which is needed by Flip Move to work. To make it work you need to wrap your functional component into React.forwardRef and pass it down to the first element which accepts refs, such as DOM elements or class components:

1import React, { forwardRef } from 'react';
2import FlipMove from 'react-flip-move';
3
4const FunctionalArticle = forwardRef((props, ref) => (
5  <div ref={ref}>
6    {props.articleName}
7  </div>
8));
9
10// you do not have to modify the parent component
11// this will stay as described in the quickstart
12const TopArticles = ({ articles }) => (
13  <FlipMove>
14    {articles.map(article => (
15      <FunctionalArticle key={article.id} {...article} />
16    ))}
17  </FlipMove>
18);

API Reference

View the full API reference documentation

Enter/Leave Animations

View the enter/leave docs

Compatibility

	Chrome	Firefox	Safari	IE	Edge	iOS Safari/Chrome	Android Chrome
Supported	✔ 10+	✔ 4+	✔ 6.1+	✔ 10+	✔	✔ 6.1+	✔

How It Works

Curious how this works, under the hood? Read the Medium post.

Wrapping Element

By default, Flip Move wraps the children you pass it in a <div>:

1// JSX
2<FlipMove>
3  <div key="a">Hello</div>
4  <div key="b">World</div>
5</FlipMove>
6
7// HTML
8<div>
9  <div>Hello</div>
10  <div>World</div>
11</div>

Any unrecognized props to <FlipMove> will be delegated to this wrapper element:

1// JSX
2<FlipMove className="flip-wrapper" style={{ color: 'red' }}>
3  <div key="a">Hello</div>
4  <div key="b">World</div>
5</FlipMove>
6
7// HTML
8<div class="flip-wrapper" style="color: red;">
9  <div key="a">Hello</div>
10  <div key="b">World</div>
11</div>

You can supply a different element type with the typeName prop:

1// JSX
2<FlipMove typeName="ul">
3  <li key="a">Hello</li>
4  <li key="b">World</li>
5</FlipMove>
6
7// HTML
8<ul>
9  <li key="a">Hello</li>
10  <li key="b">World</li>
11</ul>

Finally, if you're using React 16 or higher, and Flip Move 2.10 or higher, you can use the new "wrapperless" mode. This takes advantage of a React Fiber feature, which allows us to omit this wrapping element:

1// JSX
2<div className="your-own-element">
3  <FlipMove typeName={null}>
4    <div key="a">Hello</div>
5    <div key="b">World</div>
6  </FlipMove>
7</div>
8
9// HTML
10<div class="your-own-element">
11  <div key="a">Hello</div>
12  <div key="b">World</div>
13</div>

Wrapperless mode is nice, because it makes Flip Move more "invisible", and makes it easier to integrate with parent-child CSS properties like flexbox. However, there are some things to note:

This is a new feature in FlipMove, and isn't as battle-tested as the traditional method. Please test thoroughly before using in production, and report any bugs!
Flip Move does some positioning magic for enter/exit animations - specifically, it temporarily applies position: absolute to its children. For this to work correctly, you'll need to make sure that <FlipMove> is within a container that has a non-static position (eg. position: relative), and no padding:

1// BAD - this will cause children to jump to a new position before exiting:
2<div style={{ padding: 20 }}>
3  <FlipMove typeName={null}>
4    <div key="a">Hello world</div>
5  </FlipMove>
6</div>
7
8// GOOD - a non-static position and a tight-fitting wrapper means children will
9// stay in place while exiting:
10<div style={{ position: 'relative' }}>
11  <FlipMove typeName={null}>
12    <div key="a">Hello world</div>
13  </FlipMove>
14</div>

Gotchas

Does not work with stateless functional components without a React.forwardRef, read more about here. This is because Flip Move uses refs to identify and apply styles to children, and stateless functional components cannot be given refs. Make sure the children you pass to <FlipMove> are either native DOM elements (like <div>), or class components.
All children need a unique key property. Even if Flip Move is only given a single child, it needs to have a unique key prop for Flip Move to track it.
Flip Move clones the direct children passed to it and overwrites the ref prop. As a result, you won't be able to set a ref on the top-most elements passed to FlipMove. To work around this limitation, you can wrap each child you pass to <FlipMove> in a <div>.
Elements whose positions have not changed between states will not be animated. This means that no onStart or onFinish callbacks will be executed for those elements.
Sometimes you'll want to update or change an item without triggering a Flip Move animation. For example, with optimistic updating, you may render a temporary version before replacing it with the server-validated one. In this case, use the same key for both versions, and Flip Move will treat them as the same item.
If you have a vertical list with numerous elements, exceeding viewport, and you are experiencing automatic scrolling issues when reordering an item (i.e. the browser scrolls to the moved item's position), you can add style={{ overflowAnchor: 'none' }} to the container element (e.g. <ul>) to prevent this issue.

Known Issues

Interrupted enter/leave animations can be funky. This has gotten better recently thanks to our great contributors, but extremely fast adding/removing of items can cause weird visual glitches, or cause state to become inconsistent. Experiment with your usecase!
Existing transition/transform properties will be overridden. I am hoping to change this in a future version, but at present, Flip Move does not take into account existing transition or transform CSS properties on its direct children.

Note on `will-change`

To fully benefit from hardware acceleration, each item being translated should have its own compositing layer. This can be accomplished with the CSS will-change property.

Applying will-change too willy-nilly, though, can have an adverse effect on mobile browsers, so I have opted to not use it at all.

In my personal experimentations on modern versions of Chrome, Safari, Firefox and IE, this property offers little to no gain (in Chrome's timeline I saw a savings of ~0.5ms on a 24-item shuffle).

YMMV: Feel free to experiment with the property in your CSS. Flip Move will respect the wishes of your stylesheet :)

Further reading: CSS will-change Property

Contributions

Contributors welcome! Please discuss new features with me ahead of time, and submit PRs for bug fixes with tests (Testing stack is Mocha/Chai/Sinon, tested in-browser by Karma).

There is a shared prepush hook which launches eslint, flow checks, and tests. It sets itself up automatically during npm install.

Development

This project uses React Storybook in development. The developer experience is absolutely lovely, and it makes testing new features like enter/leave presets super straightforward.

After installing dependencies, launch the Storybook dev server with npm run storybook.

This project adheres to the formatting established by airbnb's style guide. When contributing, you can make use of the autoformatter prettier to apply these rules by running the eslint script npm run lint:fix. If there are conflicts, the linter triggered by the prepush hook will inform you of those as well. To check your code by hand, run npm run lint.

Flow support

Flip Move's sources are type-checked with Flow. If your project uses it too, you may want to install typings for our public API from flow-typed repo.

1npm install --global flow-typed # if not already
2flow-typed install react-flip-move@<version>

If you're getting some flow errors coming from node_modules/react-flip-move/src path, you should add this to your .flowconfig file:

[ignore]
.*/node_modules/react-flip-move/.*

License

MIT

No vulnerabilities found.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

4

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Maintained

Determines if the project is "actively maintained".

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Security-Policy

Determines if the project has published a security policy.

0

Fuzzing

Determines if the project uses fuzzing.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Reason

125 existing vulnerabilities detected

Details

Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
Warn: Project is vulnerable to: GHSA-v88g-cgmw-v5xw
Warn: Project is vulnerable to: GHSA-whgm-jr23-g3j9
Warn: Project is vulnerable to: GHSA-fwr7-v2mv-hh25
Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
Warn: Project is vulnerable to: GHSA-cwfw-4gq5-mrqx
Warn: Project is vulnerable to: GHSA-g95f-p29q-9xw4
Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
Warn: Project is vulnerable to: GHSA-x9w5-v3q2-3rhw
Warn: Project is vulnerable to: GHSA-257v-vj4p-3w2h
Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
Warn: Project is vulnerable to: GHSA-rq8g-5pc5-wrhr
Warn: Project is vulnerable to: GHSA-p28h-cc7q-c4fg
Warn: Project is vulnerable to: GHSA-9vvw-cc9w-f27h
Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c
Warn: Project is vulnerable to: GHSA-hr2v-3952-633q
Warn: Project is vulnerable to: GHSA-h6ch-v84p-w6p9
Warn: Project is vulnerable to: GHSA-ff7x-qrg7-qggm
Warn: Project is vulnerable to: GHSA-vh7m-p724-62c2
Warn: Project is vulnerable to: GHSA-r9p9-mrjm-926w
Warn: Project is vulnerable to: GHSA-434g-2637-qmqr
Warn: Project is vulnerable to: GHSA-49q7-c7j4-3p7m
Warn: Project is vulnerable to: GHSA-977x-g7h5-7qgw
Warn: Project is vulnerable to: GHSA-f7q4-pwc6-w24p
Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747
Warn: Project is vulnerable to: GHSA-j4f2-536g-r55m
Warn: Project is vulnerable to: GHSA-r7qp-cfhv-p84w
Warn: Project is vulnerable to: GHSA-4gmj-3p3h-gm8h
Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc
Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
Warn: Project is vulnerable to: GHSA-qrmc-fj45-qfc2
Warn: Project is vulnerable to: GHSA-8r6j-v8pm-fqw3
Warn: Project is vulnerable to: MAL-2023-462
Warn: Project is vulnerable to: GHSA-xf7w-r453-m56c
Warn: Project is vulnerable to: GHSA-4q6p-r6v2-jvc5
Warn: Project is vulnerable to: GHSA-qh2h-chj9-jffq
Warn: Project is vulnerable to: GHSA-q42p-pg8m-cqh6
Warn: Project is vulnerable to: GHSA-w457-6q6x-cgp9
Warn: Project is vulnerable to: GHSA-62gr-4qp9-h98f
Warn: Project is vulnerable to: GHSA-f52g-6jhx-586p
Warn: Project is vulnerable to: GHSA-2cf5-4w76-r9qv
Warn: Project is vulnerable to: GHSA-3cqr-58rm-57f8
Warn: Project is vulnerable to: GHSA-g9r4-xpmj-mj65
Warn: Project is vulnerable to: GHSA-q2c6-c6pm-g3gh
Warn: Project is vulnerable to: GHSA-765h-qjxv-5f44
Warn: Project is vulnerable to: GHSA-f2jv-r9rf-7988
Warn: Project is vulnerable to: GHSA-44pw-h2cw-w3vq
Warn: Project is vulnerable to: GHSA-jp4x-w63m-7wgm
Warn: Project is vulnerable to: GHSA-c429-5p7v-vgjp
Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj
Warn: Project is vulnerable to: GHSA-6x33-pw7p-hmpq
Warn: Project is vulnerable to: GHSA-qqgx-2p2h-9c37
Warn: Project is vulnerable to: GHSA-4hpf-3wq7-5rpr
Warn: Project is vulnerable to: GHSA-f522-ffg8-j8r6
Warn: Project is vulnerable to: GHSA-7r28-3m3f-r2pr
Warn: Project is vulnerable to: GHSA-r8j5-h5cx-65gg
Warn: Project is vulnerable to: GHSA-2pr6-76vf-7546
Warn: Project is vulnerable to: GHSA-8j8c-7jfh-h6hx
Warn: Project is vulnerable to: GHSA-896r-f27r-55mw
Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
Warn: Project is vulnerable to: GHSA-282f-qqgm-c34q
Warn: Project is vulnerable to: GHSA-7x7c-qm48-pq9c
Warn: Project is vulnerable to: GHSA-rc3x-jf5g-xvc5
Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488
Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g
Warn: Project is vulnerable to: GHSA-jf85-cpcp-j695
Warn: Project is vulnerable to: GHSA-fvqr-27wr-82fm
Warn: Project is vulnerable to: GHSA-4xc9-xhrj-v574
Warn: Project is vulnerable to: GHSA-x5rq-j2xg-h7qm
Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9
Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
Warn: Project is vulnerable to: GHSA-82v2-mx6x-wq7q
Warn: Project is vulnerable to: GHSA-pp57-mqmh-44h7
Warn: Project is vulnerable to: GHSA-4xcv-9jjx-gfj3
Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
Warn: Project is vulnerable to: GHSA-wrvr-8mpx-r7pp
Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m / GHSA-xvch-5gv4-984h
Warn: Project is vulnerable to: GHSA-w9mr-4mfr-499f
Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g
Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
Warn: Project is vulnerable to: GHSA-q75g-2496-mxpp
Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9
Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
Warn: Project is vulnerable to: GHSA-g6ww-v8xp-vmwg
Warn: Project is vulnerable to: GHSA-566m-qj78-rww5
Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
Warn: Project is vulnerable to: GHSA-6g33-f262-xjp4
Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
Warn: Project is vulnerable to: GHSA-4rq4-32rv-6wp6
Warn: Project is vulnerable to: GHSA-64g7-mvw6-v9qj
Warn: Project is vulnerable to: GHSA-fxwf-4rqh-v8g3
Warn: Project is vulnerable to: GHSA-25hc-qcg6-38wj
Warn: Project is vulnerable to: GHSA-xfhh-g9f5-x4m4
Warn: Project is vulnerable to: GHSA-qm95-pgcg-qqfq
Warn: Project is vulnerable to: GHSA-cqmj-92xf-r6r9
Warn: Project is vulnerable to: GHSA-2m39-62fm-q8r3
Warn: Project is vulnerable to: GHSA-mf6x-7mm4-x2g7
Warn: Project is vulnerable to: GHSA-j44m-qm6p-hp7m
Warn: Project is vulnerable to: GHSA-3jfq-g458-7qm9
Warn: Project is vulnerable to: GHSA-5955-9wpr-37jh
Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36
Warn: Project is vulnerable to: GHSA-g7q5-pjjr-gqvp
Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
Warn: Project is vulnerable to: GHSA-7p7h-4mm5-852v
Warn: Project is vulnerable to: GHSA-662x-fhqg-9p8v
Warn: Project is vulnerable to: GHSA-394c-5j6w-4xmx
Warn: Project is vulnerable to: GHSA-78cj-fxph-m83p
Warn: Project is vulnerable to: GHSA-fhg7-m89q-25r3
Warn: Project is vulnerable to: GHSA-cf4h-3jhx-xvhq
Warn: Project is vulnerable to: GHSA-mgfv-m47x-4wqp
Warn: Project is vulnerable to: GHSA-wr3j-pwj9-hqq6
Warn: Project is vulnerable to: GHSA-5v72-xg48-5rpm
Warn: Project is vulnerable to: GHSA-72mh-269x-7mh5
Warn: Project is vulnerable to: GHSA-h4j5-c7cj-74xg
Warn: Project is vulnerable to: GHSA-c4w7-xm78-47vh
Warn: Project is vulnerable to: GHSA-p9pc-299p-vxgp

Score

2.3

/10

Last Scanned on 2024-11-18

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More

Other packages similar to react-flip-move

react-images-upload

1.2.8

Simple component for upload and validate (client side) images with preview built with React.js. This package use [react-flip-move](https://github.com/joshwcomeau/react-flip-move) for animate the file preview images.

react-flip-toolkit

7.2.4

Configurable FLIP animation helpers for React

react-multi-images-uploader

0.0.4

Simple component for upload and validate (client side) images with preview built with React.js. This package use ['react-flip-move'](https://github.com/joshwcomeau/react-flip-move) for animate the file preview images.

@jimp/plugin-flip

1.6.0

react-flip-move

Installations

Pull Requests

1

105

13

91

Issues

33

173

140

Releases

Developer

Developer Guide

CommonJS

No

17.1.0

8.1.2

Statistics

Languages

Total Downloads

33,038,871

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Peer Dependencies

Dev Dependencies

React Flip Move

Current Status

Demos

Installation

Features

Quickstart

Usage with Functional Components

API Reference

Enter/Leave Animations

Compatibility

How It Works

Wrapping Element

Gotchas

Known Issues

Note on will-change

Contributions

Development

Flow support

License

10

10

4

0

0

0

0

0

0

0

2.3

/10

Other packages similar to react-flip-move

Note on `will-change`