Cinematic Scroll React (cinematic-scroll-react)

A reusable, highly-optimized React engine for building breathtaking, Apple-style scroll-controlled frame animations. Powered by GSAP and ScrollTrigger under the hood, it converts sequential image frames into high-framerate interactive visual storytelling experiences.

Inspired by industry-defining sites like the Apple AirPods Pro, SpaceX Starship, and award-winning Awwwards portfolios, cinematic-scroll-react provides a plug-and-play component architecture with cutting-edge visual telemetry.

🌟 Key Features

• 🚀 High-Performance Canvas Rendering: Uses cover-fit and contain aspect mappings inside requestAnimationFrame loops, bypassing React state re-renders to maintain a rock-solid 60fps.
• 🪐 Interactive Cosmic Particle Overlay: Dynamic floating dust particles that react to scroll velocity, scroll acceleration, and cursor interactions.
• 🛡️ SSR & Next.js Safe: Gracefully handles server-side environments via safe client-only guards (typeof window !== 'undefined').
• 💻 3D Cursor Parallax: Smooth cursor tracking and translations powered by GSAP interpolation for layered parallax depths.
• 🛰️ Glassmorphic HUD Telemetries: Plug-and-play sci-fi dashboard readouts and rotating SVG cybernetic rings out-of-the-box.
• 📖 Synchronized Narrative Slides: Scroll-scrub-synchronized text crossfades with dynamic blur filters and transitions.
• 📦 Production Ready: Full TypeScript support, ESM + CommonJS formats, and automatic tree-shaking support.
• ⚙️ Intelligent Caching Preloader: sequetially downloads and memoizes image frames with robust error tolerance to prevent hanging states.

📦 Installation

To install cinematic-scroll-react along with its peer dependencies:

npm i @idrtech/cinematic-scroll-react

🚀 Quick Start

Here is how you can build an immersive, Apple-style hero section in seconds:

import React from 'react';
import { CinematicScroll } from 'cinematic-scroll-react';

// 1. Define sequence URLs
const FRAME_COUNT = 150;
const frames = Array.from(
  { length: FRAME_COUNT },
  (_, i) => `/images/astronaut-frame-${String(i + 1).padStart(3, '0')}.jpg`
);

// 2. Define storytelling narrative slides
const slides = [
  {
    label: 'DEEP SPACE INITIATIVE // ARES VII',
    title: 'BEYOND\nTHE SILENCE',
    sub: 'Where light fades and time bends, one soul drifts through the infinite dark.',
  },
  {
    label: 'NEURAL INTEGRATION // STAGE 02',
    title: 'DESIGNING\nTHE FUTURE',
    sub: 'Where creativity meets intelligence, we engineer next-generation immersive realities.',
  },
  {
    label: 'SOLITARY SYSTEM LAUNCH',
    title: 'BEYOND\nIMAGINATION',
    sub: 'The voyage into deep space has begun. Ares VII singularity engines are fully primed.',
  }
];

export default function HeroSection() {
  return (
    <div style={{ width: '100%' }}>
      <CinematicScroll
        frames={frames}
        textSlides={slides}
        scrollLength={5000} // Total scroll height in pixels for scrubbing
        scrub={0.5}        // Scrub lag for smooth inertia
        zoomScale={1.15}    // Subtle zoom-in scale as you scroll
      />
    </div>
  );
}

🛰️ Advanced Customization

1. Parallax Layers & Custom Overlays

You can easily wrap individual floating widgets or assets inside the <ParallaxLayer> to make them move relative to the user's mouse with distinct coefficients:

import { CinematicScroll, ParallaxLayer } from 'cinematic-scroll-react';

export default function CustomHero() {
  return (
    <CinematicScroll frames={frames} enableHUD={false}>
      {/* Element that drifts opposite to cursor */}
      <ParallaxLayer strength={30} invert>
        <div className="custom-floating-badge">
          SECTOR 09 LOCKED
        </div>
      </ParallaxLayer>
      
      {/* Element that drifts along with cursor */}
      <ParallaxLayer strength={15}>
        <div className="custom-diagnostics-panel">
          REACTOR TEMP: 293 K
        </div>
      </ParallaxLayer>
    </CinematicScroll>
  );
}

2. Customizing particles

The interactive dust simulator can be styled or disabled to suit your design requirements:

<CinematicScroll
  frames={frames}
  particleCount={120}                         // Denseness of dust field
  particleColor="rgba(212, 175, 55, 0.5)"     // Elegant gold dust HSL/RGBA
  effects={{
    particles: true,                          // Toggle dust overlay
    parallax: true,                           // Toggle mouse cursor parallax depth
    blur: true,                               // Toggle blur crossfading on narrative text
  }}
/>

⚙️ Props Reference

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | frames | string[] | Required | Array of sequential image asset URLs to load and scrub. | | textSlides | TextSlide[] | [] | Narrative text blocks to fade in/out during scrolling. | | scrollLength | number | 5000 | Scrolling distance in pixels that controls scrub duration. | | scrub | number \| boolean | 0.5 | Timeline scrubbing inertia. Lower numbers result in snappier movement; higher values feel more fluid. | | zoomScale | number | 1.15 | The scaling factor applied to the canvas cover at the end of the scroll trigger. | | effects | CinematicEffects | all: true | Visual effects switches (particles, blur, glow, parallax). | | particleCount | number | 80 | Quantity of floating space dust particles. | | particleColor | string | rgba(212,175,55,0.4) | Color signature applied to particles (radial gradients). | | enableHUD | boolean | true | Toggles the retro-futuristic telemetry overlays and rotating central SVG dashboard. | | hudTelemetry | HUDTelemetry | Default stats | Custom telemetry readings and diagnostics to display on the glass HUD. | | loaderStyle | 'default' \| 'futuristic' \| 'minimal' \| 'none' | 'default' | Aesthetic design theme for the preloading sequence. | | onScrollProgress| (progress: number) => void| undefined| Callback fired on scroll updates; reports scrub ratio (0.0 to 1.0). | | onLoadComplete | () => void | undefined | Callback fired once all frames are downloaded and ready. |

🛠️ Build & Dev Compilation

To compile or customize the package locally:

1. Install dependencies: npm install
2. Run build: npm run build
3. The build compiles type definition mappings and outputs ESM and UMD bundles into /dist.

📄 License

MIT © Indrajit Padhiyar