react-framo

react-framo

🎬 Demo

▶️ Try it

Version: 1.0.0
A lightweight React hook for creating smooth frame-by-frame scroll animations using canvas.

✨ Features

• Scroll-based frame-by-frame animations.
• Canvas rendering for smooth performance.
• Plug and play with custom base path or image URLs.
• Exposes loading status and current frame index.
• Fully customizable scroll range and image options.

📦 Installation

Using npm:

npm install react-framo

🚀 Basic Usage Example

import React from "react";
import { motion } from "motion/react";
import { useFrameSequence } from "react-framo";

function App() {
  const { canvasRef, currentIndex, isLoaded } = useFrameSequence({
    basePath: "/Assets/Extracted-Frames/frame_",
    frameCount: 121,
    scrollRange: [0, 0.7],
    fileExtension: "jpeg",
  });

  return (
    <div style={{ height: "300vh", background: "#000" }}>
      {!isLoaded && (
        <p style={{ color: "#fff", position: "fixed", top: 20, left: 20 }}>
          Loading frames...
        </p>
      )}
      <motion.canvas
        ref={canvasRef}
        style={{
          position: "sticky",
          top: 0,
          width: "100%",
          height: "100vh",
        }}
      />
    </div>
  );
}

export default App;

🔧 Options

Option	Type	Required	Description
basePath	string	✅	Base path for your frames, excluding frame number and file extension
frameCount	number	✅	Total number of frames
scrollRange	[number, number]	❌	Scroll percentage range for animation (between 0 and 1) — default: [0, 1]
fileExtension	string	❌	File extension for images — default: "jpeg"
frames	string[]	❌	Alternative to basePath — use array of full image URLs instead

📤 Return Values

Return Value	Type	Description
canvasRef	React.RefObject	Attach this to your <canvas />
currentIndex	number	Current frame index (1-based)
isLoaded	boolean	Whether all frames are fully loaded

📁 Folder Structure for Frames

If you're using basePath, your folder should look like this:

/Assets/Extracted-Frames/
  ├── frame_0001.jpeg
  ├── frame_0002.jpeg
  ├── ...
  └── frame_0121.jpeg

✅ Make sure file names are zero-padded to match the expected format.

💡 Tips

• Use consistent naming like frame_0001.jpeg, frame_0002.jpeg, etc.
• Customize scroll animation range with scrollRange.
• Use the frames array if your images are hosted remotely or have custom names.

📃 License

MIT © Prathamesh Shelke