@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.