@xata.io/react-flipbook

🌈 A React library that puts users in control of animations.

Demos

Pick your preference. You can easily learn about this project in the following ways:

• See it in action on our live demo site.
• Watch an explainer on YouTube.
• Read about the details on the Xata Blog.

Motivation

Sometimes, a bunch of animated GIFs playing around each other can feel a bit anxiety inducing, kind of like in the example. As an alternative, we'd like a way to have more control over key frames in an image sequence, like in this example.

Features

• 🔥 Virtualization out of the box. We preload adjacent images in your frame stack and only show 3: the previous, the current, and the next. Since the whole point of this library is to not cause anxiety with fast motion, these should suffice for reasonable frame rates.
• 🔥 smol. This library is 2.8kB before gzip compression and 1.3kB after. It is the smallest React library of its kind, with others usually weighing in at around 16kB (>10x this size).
• 🔥 Multiple control modes. You know that amazing iPhoto scrubbing feature? Yeah, you can do that with this library. You can also have an auto-crossover, or bind frames to an external HTML control element. More in the demos.
• 🔥 Bring your own image component. Some people like next/image, others like some other abstraction on HTML's <img>. This library will let you choose whatever you want.
• 🔥 First-class support for ServiceWorker. Load image frames extremely fast (~1 millisecond) using intellingent ServiceWorker caching out of the box.

Usage

First, install this with npm or yarn like so:

npm install @xata.io/react-flipbook

Then, import it and use it:

import { Flipbook } from "@xata.io/react-flipbook";

const Index = () => {
  return (
    <Flipbook
      frames={[
        { alt: "Random Image 1", src: "https://picsum.photos/1024/768?v=1" },
        { alt: "Random Image 2", src: "https://picsum.photos/1024/768?v=2" },
        { alt: "Random Image 3", src: "https://picsum.photos/1024/768?v=3" },
        { alt: "Random Image 4", src: "https://picsum.photos/1024/768?v=4" },
        { alt: "Random Image 5", src: "https://picsum.photos/1024/768?v=5" },
      ]}
    />
  );
};

export default Index;

Props

Flipbook has a few universal props that apply across all flip-modes.

Option	Description	Required	Default Value
frames	An array of objects with src and alt properties that represent a single frame of the animation.	yup
mode	Our mode of flipping the flip book. Choose from auto (crossfade), scrub, or controlled. More about these below.	nope	auto
ImageComponent	An alternative image component to be used instead of <img>.	nope	img
containerStyle	An object of CSS properties you'd like to apply to the container div of this thing.	nope
serviceWorkerUrl	A URL to a ServiceWorker that can help cache your images and reduce flicker. More on this below.	nope

When you select different modes of Flipbook, you get more props. Let's expore these.

mode: "auto"

These are the extra props you can specify when your flipbook plays automatically:

Option	Description	Required	Default Value
flipDelayMs	A number in milliseconds of how long to wait until we crossfade to the next image.	nope	1200

mode: "controlled"

These are the extra props you can specify when your flipbook plays automatically:

Option	Description	Required	Default Value
currentFrameIndex	A number representing the index of the expected frame to be active	yup

Using with ServiceWorker

An issue with replacing images as quickly as we do in this library, is sometimes the browser needs time to load them on-demand. This can be a bit annoying, especially if we don't have options to cache images on the server side. To remedy this, we ship a ServiceWorker with this library that handles all the caching for you. To use it, you'll find a public/sw.js inside this project's folder in your node_modules/@xata.io/react-flipbook.

You'll want to host this somewhere on your website's deployment. If you're using Next.js, you can copy this to your public folder and it'll be available at /sw.js. Other platforms have other rules. What we're after is just a URL to this file on your same origin. Once you have this URL, you can pass it to Flipbook like so, and the rest is taken care of.

import { Flipbook } from "@xata.io/react-flipbook";

const Index = () => {
  return (
    <Flipbook
      serviceWorkerUrl="/to/your/serviceworker.js"
      frames={[
        { alt: "lol", src: "https://picsum.photos/1024/768?v=1" },
        { alt: "lol", src: "https://picsum.photos/1024/768?v=2" },
        { alt: "lol", src: "https://picsum.photos/1024/768?v=3" },
        { alt: "lol", src: "https://picsum.photos/1024/768?v=4" },
        { alt: "lol", src: "https://picsum.photos/1024/768?v=5" },
      ]}
    />
  );
};

export default Index;

Contributing

You're always welcome to open an issue if you encounter any, or even better, open a PR directly to solve issues. We don't (yet) have more contributing guidelines than this because the project is quite small. This may change as things develop.

Made with ❤️ in Berlin.