react-sequ

A lightweight React component for rendering high-performance image sequence animations using HTML5 Canvas.

react-sequ allows you to create smooth image sequence animations with support for autoplay, manual frame control, and progress-based animation. It works well for landing pages, product showcases, interactive storytelling, and scroll-driven experiences.

Installation

npm install @chunsky/react-sequ

Import

import { ImageSequence } from "@chunsky/react-sequ";
import "@chunsky/react-sequ/styles.css";

JavaScript (JSX)

Basic Usage

import { ImageSequence } from "@chunsky/react-sequ";
import "@chunsky/react-sequ/styles.css";

export default function App() {
  return (
    <ImageSequence
      src="/frames"
      prefix="frame-"
      extension="jpg"
      start={0}
      end={240}
      padding={3}
      scrollControl
      className="animation"
    />
  );
}

TypeScript (TSX)

Basic Usage

import { ImageSequence } from "@chunsky/react-sequ";
import "@chunsky/react-sequ/styles.css";

export default function App() {
  return (
    <ImageSequence
      src="/frames"
      prefix="frame-"
      extension="jpg"
      start={0}
      end={240}
      padding={3}
      scrollControl
      className="animation"
    />
  );
}

CSS (Recommended)

When using scrollControl, create a scrollable section for the animation.

.hero-section {
  height: 500vh;
}

.hero {
  position: sticky;
  top: 0;
  height: 100vh;
}

.animation {
  width: 100%;
  height: 100%;
}

Then use the component like this:

<section className="hero-section">
  <div className="hero">
    <ImageSequence
      src="/frames"
      prefix="frame-"
      extension="jpg"
      start={0}
      end={240}
      padding={3}
      scrollControl
      className="animation"
    />
  </div>
</section>

The 500vh value determines how much scroll distance is available for the animation. You can increase or decrease it depending on how long you want the animation to play.

Scroll Animation

react-sequ does not include its own scroll engine.

Simply pass a value between 0 and 1 to the progress prop. This value can come from:

• Native scroll events
• GSAP ScrollTrigger
• Framer Motion
• Lenis
• locomotive-scroll
• React Spring
• Any animation library

Example:

<ImageSequence
  src="/frames"
  prefix="frame-"
  extension="jpg"
  start={0}
  end={240}
  padding={3}
  progress={progress}
/>

Manual Frame Control

Display a specific frame directly.

<ImageSequence
  src="/frames"
  prefix="frame-"
  extension="jpg"
  start={0}
  end={240}
  padding={3}
  frame={120}
/>

Using an Array of Images

<ImageSequence
  sources={[
    "/frames/000.jpg",
    "/frames/001.jpg",
    "/frames/002.jpg",
    "/frames/003.jpg"
  ]}
/>

Using a Path Template

Using ####

<ImageSequence
  path="/frames/frame-####.jpg"
  start={0}
  end={240}
/>

Using {index}

<ImageSequence
  path="/frames/frame-{index}.jpg"
  start={0}
  end={240}
  padding={3}
/>

Folder Structure

public/
└── frames/
    ├── frame-000.jpg
    ├── frame-001.jpg
    ├── frame-002.jpg
    └── ...

Props

| Prop | Type | Default | Description | | ---------------- | ----------------------- | ---------------------------- | ----------------------------------------- | | sources | string[] | — | Explicit image URL array. | | path | string | — | Image template using #### or {index}. | | src | string | — | Image directory. | | prefix | string | "" | Filename prefix. | | extension | string | — | Image extension. | | start | number | — | First frame. | | end | number | — | Last frame. | | padding | number | 0 | Zero-padding width. | | progress | number | — | Animation progress (0 → 1). | | frame | number | — | Display an exact frame. | | autoPlay | boolean | false | Enable automatic playback. | | fps | number | 24 | Playback speed. | | fit | "cover" | "contain" | "cover" | Canvas image fitting mode. | | className | string | "" | CSS class applied to the canvas. | | style | CSSProperties | — | Inline styles for the canvas. | | alt | string | "Image sequence animation" | Accessible label. | | onLoadProgress | function | — | Loading progress callback. | | onFrameChange | function | — | Called whenever the frame changes. |

Browser Support

• Chrome
• Edge
• Firefox
• Safari

License

MIT

Author

Created by Chunsky

💖 Support

If you enjoy using React Sequ, you can support its development:

Your support helps maintain the project, improve features, fix bugs, and continue developing open-source software.