React

November 11, 2025• 11 min read

Cinematic Scroll-Driven Video Experiences in React

A cinematic scroll transforms simple scrolling into a narrative lens: every gesture becomes an interaction, every reveal a transition. Done right, it turns passive visitors into active participants, boosting engagement, dwell time, and shareability.

Also published on:

Medium

React

Animation

GSAP

Scroll

The Scene We'll Bring to Life

A scroll-controlled sequence where a lone cowboy rides at sunset, fading to bright grayscale, revealing the logo through a zooming mask, and ending with a clean brand lockup.

Demo

Live Preview

Playground: Open it in CodeSandbox to explore the source code.

Repository

Browse the full project on GitHub to see the complete structure and implementation details.

Thinking Like a Director

Before diving into the steps, let's look at this concept through a director's eyes. In film, every frame serves the story. On the web, every scroll event can do the same. Our architecture borrows filmmaking terms for clarity:

Scene: CinematicScene. Controls and coordinates all visual layers.
Shot: <video>. The main video element tied to scroll progress.
Screenplay: GSAP timeline. Defines the animation flow and pacing.
Stage: Scroll container. Provides space for the narrative.
Mask / Logo: SVG overlays. Used for brand reveals and transitions.
Acts: Timeline segments. Define phases of the animation such as Intro → Reveal → Fade.

This perspective gives engineers and designers a shared language focused on rhythm, emotion, and pacing rather than pixels.

With the idea in mind, let's start building it step by step.

Step 1: Setting Up GSAP

For this cinematic animation system, we use GSAP (GreenSock Animation Platform), a JavaScript library that provides fine-grained control over animations and timelines. It helps synchronize video playback and effects with scroll position in a clean, performant way.

Install it with npm or pnpm (used in this project):

pnpm add gsap @gsap/react
# or
npm i gsap

Step 2: Project Structure

Our cinematic system is split into modular, testable units that separate UI, logic, and data handling. This makes the project scalable and easy to debug.

src/
├── App.tsx
├── cinematic-scene/
│   ├── cinematic-scene.tsx           # Scene orchestrator
│   ├── components/
│   │   ├── CinematicShot.tsx         # Renders and synchronizes the video element
│   │   └── SceneOverlay.tsx          # Displays logo mask and overlays
│   ├── hooks/
│   │   ├── useScreenplayAnimation.ts # Manages GSAP scroll-based animation logic
│   │   ├── useShotPreload.ts         # Handles video preload and buffering
│   ├── styles/
│   │   └── cinematic-scene.css
│   ├── types/
│   │   └── cinematic.types.ts
│   └── utils/
│       └── screenplay.utils.ts       # GSAP timeline creation
└── contexts/
    └── VideoLoadingContext.tsx       # Manages video readiness state

Step 3: Building the CinematicScene Component

This is the main orchestrator that unites the video shot, overlays, preloading, and animation logic. It manages references, loading states, and coordinates the GSAP timeline through custom hooks.

import type { CinematicSceneProps } from './types/cinematic.types'

import React, { useCallback, useEffect, useRef, useState } from 'react'

import { useVideoLoading } from '../contexts/VideoLoadingContext'
import { CinematicShot } from './components/CinematicShot'
import { SceneOverlay } from './components/SceneOverlay'
import { useScreenplayAnimation } from './hooks/useScreenplayAnimation'
import { useShotPreload } from './hooks/useShotPreload'

/**
 * CinematicScene - Orchestrates a scroll-driven cinematic experience
 * Composes shot, overlays, and screenplay animations into a cohesive scene
 *
 * Cinema Metaphor:
 * - Scene: The complete visual sequence
 * - Shot: The video element being played
 * - Screenplay: The animation timeline
 * - Stage: The container for the shot
 * - LogoMask: Colored branding that masks the video during zoom-out (brand-colored.svg)
 * - HeroLogo: Main brand identity with original colors (brand-hero.svg)
 */
export const CinematicScene: React.FC<CinematicSceneProps> = ({ src, duration = '300vh' }) => {
  // Scene element references
  const shotRef = useRef<HTMLVideoElement>(null)
  const stageRef = useRef<HTMLDivElement>(null)
  const logoMaskRef = useRef<HTMLDivElement>(null)
  const heroLogoRef = useRef<HTMLDivElement>(null)
  const sceneRef = useRef<HTMLDivElement>(null)

  // Track loading states
  const [isBlobReady, setIsBlobReady] = useState(false)
  const [isBufferReady, setIsBufferReady] = useState(false)

  // Get video loading context
  const { setVideoReady } = useVideoLoading()

  // Handle blob creation complete
  const handleBlobReady = useCallback(() => {
    console.log('Blob is ready')
    setIsBlobReady(true)
  }, [])

  // Check if both conditions are met
  useEffect(() => {
    if (isBlobReady && isBufferReady) {
      console.log('Both blob and buffer ready - marking video as ready')
      setVideoReady()
    }
  }, [isBlobReady, isBufferReady, setVideoReady])

  // Orchestrate the cinematic experience
  useShotPreload({ shotRef, src, onBlobReady: handleBlobReady })
  useScreenplayAnimation({
    shotRef,
    stageRef,
    logoMaskRef,
    heroLogoRef,
    sceneRef,
    src,
  })

  // Monitor video buffer status
  useEffect(() => {
    const video = shotRef.current
    if (!video) return

    console.log('Starting video buffer monitoring')
    let isReady = false

    // Check video buffer
    const checkBuffer = () => {
      if (isReady) return false

      const buffered = video.buffered
      const duration = video.duration

      // Check if we have at least 2 seconds buffered OR 30% of video buffered
      if (buffered.length > 0 && duration > 0) {
        const bufferedEnd = buffered.end(buffered.length - 1)
        const bufferedAmount = bufferedEnd
        const bufferPercentage = (bufferedAmount / duration) * 100

        console.log(
          `Video buffer: ${bufferedAmount.toFixed(2)}s / ${duration.toFixed(2)}s (${bufferPercentage.toFixed(1)}%)`,
        )

        // Wait for meaningful buffer: 2s minimum OR 30% of video
        if (bufferedAmount >= 2 || bufferPercentage >= 30) {
          console.log('Video has sufficient buffer')
          isReady = true
          setIsBufferReady(true)
          return true
        }
      }
      return false
    }

    // Listen for progress events to check buffer
    const handleProgress = () => {
      if (video.readyState >= 3) {
        checkBuffer()
      }
    }

    // Multiple strategies to detect when video has data
    video.addEventListener('progress', handleProgress)
    video.addEventListener('canplay', checkBuffer)
    video.addEventListener('canplaythrough', checkBuffer)
    video.addEventListener('loadeddata', checkBuffer)

    // Check immediately if already loaded
    if (video.readyState >= 3) {
      setTimeout(checkBuffer, 100)
    }

    // Fallback timeout - ensure we don't block forever
    const fallbackTimeout = setTimeout(() => {
      if (!isReady) {
        console.log('Buffer check timeout - marking as ready anyway')
        isReady = true
        setIsBufferReady(true)
      }
    }, 8000)

    return () => {
      video.removeEventListener('progress', handleProgress)
      video.removeEventListener('canplay', checkBuffer)
      video.removeEventListener('canplaythrough', checkBuffer)
      video.removeEventListener('loadeddata', checkBuffer)
      clearTimeout(fallbackTimeout)
    }
  }, [src])

  return (
    <div ref={sceneRef}>
      <div ref={stageRef}>
        <CinematicShot src={src} shotRef={shotRef} duration={duration} />
      </div>

      <SceneOverlay logoMaskRef={logoMaskRef} heroLogoRef={heroLogoRef} />
    </div>
  )
}

Step 4: Implementing the useScreenplayAnimation Hook

This hook manages scroll-driven interactions and ensures GSAP animations start only when the video is ready. It also handles touch activation for iOS and cleans up properly when unmounted.

import type { ScreenplayAnimationConfig } from '../types/cinematic.types'

import { useGSAP } from '@gsap/react'
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

import { activateShot, createScreenplay } from '../utils/screenplay.utils'

gsap.registerPlugin(ScrollTrigger)

/**
 * Custom hook for orchestrating cinematic screenplay animations
 * Manages scroll-based shot sequencing and visual narrative
 */
export const useScreenplayAnimation = ({
  shotRef,
  stageRef,
  logoMaskRef,
  heroLogoRef,
  sceneRef,
  src,
}: ScreenplayAnimationConfig): void => {
  useGSAP(
    () => {
      const shot = shotRef.current
      const stage = stageRef.current
      const logoMaskContainer = logoMaskRef.current
      const heroLogoContainer = heroLogoRef.current

      if (!shot || !stage) return

      const logoMask = stage.nextElementSibling?.querySelector('svg')
      if (!logoMask) return

      // Setup touch activation for iOS
      const handleActivateShot = (): void => activateShot(shot)
      document.documentElement.addEventListener('touchstart', handleActivateShot, { once: true })

      // Setup screenplay when video is fully ready
      const handleVideoReady = (): void => {
        // Ensure video is ready and has valid duration
        if (!shot.duration || isNaN(shot.duration) || !isFinite(shot.duration)) {
          console.warn('Video duration not ready, retrying...', shot.duration)
          // Retry after a short delay
          setTimeout(handleVideoReady, 100)
          return
        }

        // Double-check readyState
        if (shot.readyState < 2) {
          console.warn('Video not ready, waiting for data...', shot.readyState)
          setTimeout(handleVideoReady, 100)
          return
        }

        console.log('Video ready! Duration:', shot.duration, 'ReadyState:', shot.readyState)

        const screenplay = createScreenplay({
          shot,
          stage,
          logoMask: logoMask as SVGElement,
          logoMaskContainer,
          heroLogoContainer,
        })

        // Attach scroll trigger to screenplay
        ScrollTrigger.create({
          trigger: stage,
          start: 'top top',
          end: 'bottom bottom',
          scrub: 1,
          animation: screenplay,
          invalidateOnRefresh: true,
        })
      }

      // Listen to multiple events to ensure video is ready
      shot.addEventListener('loadedmetadata', handleVideoReady, { once: true })
      shot.addEventListener('loadeddata', handleVideoReady, { once: true })
      shot.addEventListener('canplay', handleVideoReady, { once: true })

      // Fallback: try after a timeout if events don't fire
      const fallbackTimeout = setTimeout(() => {
        console.warn('Fallback: forcing video ready check')
        handleVideoReady()
      }, 2000)

      return () => {
        clearTimeout(fallbackTimeout)
        shot.removeEventListener('loadedmetadata', handleVideoReady)
        shot.removeEventListener('loadeddata', handleVideoReady)
        shot.removeEventListener('canplay', handleVideoReady)
        document.documentElement.removeEventListener('touchstart', handleActivateShot)
        ScrollTrigger.getAll().forEach((trigger) => trigger.kill())
      }
    },
    { scope: sceneRef, dependencies: [src] },
  )
}

Step 5: The Screenplay of a Scroll-Driven Narrative

This GSAP timeline defines the entire cinematic flow of the animation and synchronizes video playback with scroll progress.

import type { ScreenplayRefs } from '../types/cinematic.types'

import gsap from 'gsap'

/**
 * Creates GSAP screenplay for cinematic shot animation
 * Orchestrates the visual narrative through scroll-based keyframes
 */
export const createScreenplay = (refs: ScreenplayRefs): gsap.core.Timeline => {
  const { shot, logoMaskContainer, logoMask, heroLogoContainer } = refs

  const screenplay = gsap.timeline({ defaults: { duration: 1 } })

  // Get video duration safely
  const videoDuration =
    shot.duration && !isNaN(shot.duration) && isFinite(shot.duration) ? shot.duration : 10 // fallback duration

  // Act 1: Sync shot playback with scroll
  screenplay.fromTo(
    shot,
    { currentTime: 0 },
    {
      currentTime: videoDuration,
      ease: 'none',
      duration: 1,
      onUpdate: function () {
        // Force update currentTime
        const progress = this.progress()
        const newTime = progress * videoDuration

        if (newTime >= 0 && newTime <= videoDuration && !isNaN(newTime)) {
          try {
            shot.currentTime = newTime
          } catch (e) {
            console.warn('Failed to set currentTime:', e)
          }
        }
      },
    },
  )

  // Act 2: Brighten and desaturate shot (fade to white for a classic black-and-white movie feel)
  screenplay.fromTo(
    shot,
    { filter: 'brightness(1) saturate(1)' },
    { filter: 'brightness(5) saturate(0)', duration: 0.3, ease: 'power2.in' },
    '-=0.4',
  )

  // Act 3: Fade in logo mask container
  if (logoMaskContainer) {
    screenplay.fromTo(logoMaskContainer, { opacity: 0 }, { opacity: 1, duration: 0.3 }, '-=0.2')
  }

  // Act 4a: Animate logo mask (zoom in from distance)
  screenplay.fromTo(
    logoMask,
    { scale: 25, x: 3050, y: 900, opacity: 1 },
    {
      scale: 0.3,
      x: 0,
      y: 0,
      opacity: 1,
      duration: 0.7,
      ease: 'power2.out',
    },
    '-=0.3',
  )

  // Act 4b: Logo Mask Color transition to red (separate timeline for filter)
  screenplay.fromTo(
    logoMask,
    { filter: 'brightness(2) saturate(6) hue-rotate(-11deg) contrast(1)' },
    {
      filter: 'brightness(1.3) saturate(6) hue-rotate(-11deg) contrast(0.5)',
      duration: 0.3,
      ease: 'power2.out',
    },
    '<',
  )

  // Act 5: Animate hero logo (main brand reveal with original colors)
  if (heroLogoContainer) {
    screenplay.fromTo(
      heroLogoContainer,
      { scale: 25, x: 3050, y: 900, opacity: 0 },
      { scale: 0.3, x: 0, y: 0, duration: 0.7, ease: 'power2.out' },
      '<',
    )
    screenplay.fromTo(heroLogoContainer, { opacity: 0 }, { opacity: 1, duration: 0.2 }, '-=0.2')
  }

  // Final Act: Fade out shot and logo mask
  screenplay.to(shot, { opacity: 0, duration: 0.2 }, '-=0.2')

  screenplay.to(logoMaskContainer, { opacity: 0, duration: 0.2 }, '>')

  return screenplay
}

Breakdown of Acts

Act 1: Scroll-Controlled Playback Links the video's playback directly to the scroll position, giving users the feeling of controlling the scene. This is the foundation of the cinematic illusion.

⚠️ Performance Tip: Works best at 30fps for smooth synchronization. If playback feels choppy or laggy, convert your video to 30fps using Video2Edit.

Act 2: Cinematic Glow Transition The video gradually brightens and loses its color, creating a soft fade to white moment that evokes the look of old black-and-white movies and adds a nostalgic cinematic tone before the logo reveal.

Act 3 & 4: Logo Mask Reveal (Most Challenging Segment) This is the most technically demanding part of the sequence. The brand logo appears by showing the video only through the shape of the logotype. The effect is created using mix-blend-mode: multiply with proper z-index layering, keeping the video below and the logo above.

.scroll-video-player {
  position: sticky;
  top: 0;
  width: 100%;
  height: 100vh;
  object-fit: cover;
  display: block;
  z-index: 1;
  inset: 0;
  /* Performance optimizations */
  will-change: transform;
  transform: translateZ(0);
  backface-visibility: hidden;
}

.mask-container {
  mix-blend-mode: multiply;
  color: white;
  background: black;
}

.mask-container , .logo-container {
  position: absolute;
  top: 0;
  height: 100vh;
  width: 100%;
  pointer-events: none;
  display: flex;
  align-items: center;
  justify-content: center;
  flex-direction: column;
  z-index: 2;
  opacity: 0;
  backface-visibility: hidden;
}

Then, in Act 4, the mask scales and moves into focus as the video slowly transitions into a rich red tone, creating a dramatic visual moment.

Although this step is complex, it results in a powerful and visually stunning effect.

Act 5: The hero logo enters in its original color.

Final Act: Smoothly fades out video and mask, resetting for the next sequence.

Performance Optimization and Best Practices

Creating cinematic scroll experiences requires more than beautiful animation. It needs consistent, high-performance execution. Follow these techniques to keep your animations smooth and reliable:

One ScrollTrigger per narrative to prevent overlapping playheads.
Use fromTo() to avoid cached start values.
Create timelines only after video metadata is ready.
Merge small tweens to minimize layout recalculations.
Use blob caching and readiness gates to avoid buffering.
Be sure to include muted and playsInline attributes, enabling touch activation on Safari.
Call URL.revokeObjectURL on unmount to prevent memory leaks.

Where This Approach Shines: Industries and Use Cases

Scroll-driven storytelling is more than a visual trick. It is a way to communicate through rhythm and movement, helping brands and creators turn motion into emotion. The same technique that powers a cinematic logo reveal can reshape how people experience digital stories across many industries.

🎮 Entertainment and Gaming

Game studios and entertainment platforms can transform their landing pages into interactive previews that mirror the game's atmosphere and mechanics. Instead of showing static screenshots or auto-playing trailers, scroll-driven sequences let players control the reveal, scrolling through epic battles, exploring virtual worlds, or witnessing character transformations frame by frame. This hands-on approach creates anticipation and emotional investment before the player even clicks "Play." It's particularly powerful for story-driven games, where the narrative unfolds gradually, or for gameplay mechanics that benefit from step-by-step demonstration. By giving visitors agency over the pacing, you turn passive promotion into active discovery.

🏛️ Tourism and Cultural Storytelling

Tourism platforms and museums can use scroll-driven storytelling to turn browsing into an experience. As users move through the page, they travel across landscapes, eras, or artworks, feeling time and emotion unfold naturally. Each scroll becomes a step in the journey, revealing destinations, history, or culture in a way that feels alive and memorable.

Of course, there are other approaches like 360° views that let users explore freely, but this one guides them through the story in a clear and intentional way, shaped with the mindset of a director to evoke feeling, emotion, and connection.

🏎️ Automotive and Luxury Brands

Car makers, fashion labels, and premium products can replace static visuals with scroll-based storytelling that highlights design, texture, and motion. Visitors experience the product instead of just viewing it, which helps express quality and craftsmanship in a more sensory way.

🧬 Technology and Innovation

Tech companies can use this approach to explain complex ideas, visualize data, or reveal products step by step. Motion becomes a teaching tool that guides the viewer through transformation and discovery, making information easier to grasp and remember.

🎬 Media and Streaming Platforms

Film studios and streaming services can create interactive teasers that unfold with the scroll, turning promotional pages into small cinematic journeys. It keeps viewers curious and encourages them to explore more deeply before watching the full story.

The Final Word: The Filmmaker's Mindset for Developers

Every great visual story, on screen or on the web, begins with intent. Code, like film, is a language of motion, timing, and emotion. The way you move elements on a screen shapes how users feel, focus, and remember.

Give every motion meaning. Don't animate for the sake of movement; let each transition serve the moment or guide attention.
Pace the rhythm. In film, silence builds anticipation, and in UI, a pause or gentle fade can say more than speed.
Prioritize performance. Even a slight delay or dropped frame can break immersion, so keep animations lean and responsive.
Design modularly. Reusable hooks, scenes, and timelines make iteration faster and collaboration easier.
Document your vision. Treat your timelines like storyboards so others can understand and refine the sequence you're creating.

A filmmaker's mindset helps developers think beyond pixels and transitions, shaping interactions that feel alive, meaningful, and cinematic.

Inspired by

The cinematic pacing, framing, and logo reveal style of Rockstar Games' Grand Theft Auto VI.

References

Back to Articles