GSAP Video Scroll
Let visitors scroll through a video, frame by frame.
A real video that plays forwards and backwards with the scroll, powered by GSAP — the section holds still while visitors move through it, with captions that fade in and out at the moments you choose.
Gutenberg block
Requirements
- The block editor (Gutenberg)
- WordPress 6.5 or newer
- PHP 7.4 or newer
- Moduly with GSAP built in (the release after 0.4.2). On an older Moduly the video shows with normal play controls.
Prepare the video
Scrubbing jumps to a new moment many times a second, and a browser can only show a frame quickly when the file has a keyframe close to it. Ordinary camera and web exports have one keyframe every few seconds, so they seek in visible steps. Re-encode the clip with frequent keyframes and no sound:
ffmpeg -i input.mov -an -c:v libx264 -g 5 -crf 23 -pix_fmt yuv420p -movflags +faststart scroll.mp4-g 5puts a keyframe every 5 frames;-g 1(every frame) is smoothest but makes a bigger file.-androps the sound — the video always plays muted.- Keep it short and modest in size (a few seconds, 1280–1920 px wide, under ~30 MB) so it can be preloaded whole.
Add it to a page
- Open the page or post in the block editor.
- Click + (Block Inserter) and search for GSAP Video Scroll — it is in the Moduly · GSAP category. Two ready-made layouts are under Patterns → Moduly (pick your video after inserting one).
- Choose a video from the media library, upload one, or paste a direct video link.
- Add a poster and captions and style it in the right sidebar (Block tab).
Settings
Video
| Setting | What you can set |
|---|---|
| Source | Media Library, External URL (a direct .mp4 / .webm link, not a YouTube or Vimeo page) or Image sequence |
| Video / Video URL | The clip to scrub |
| Frames · Load frames · Image smoothing | Image sequence: the images in the gallery's order (same size, 30–150 of them scrub well), loaded as the section comes near or with the page; Crisp keeps hard pixel edges when scaled |
| Poster image | Shown until the video loads and to visitors who prefer reduced motion |
| Accessible description | What the video shows, for screen readers. Empty: treated as decoration while it scrubs |
| Preload whole file up to (MB) | 0–200. Smaller files are downloaded completely as the section comes near; larger ones are buffered by the browser |
Scroll
| Setting | What you can set |
|---|---|
| Playback | Scrub with the scroll (default) or Play in view — the video plays on its own while it is on screen and pauses when it leaves (not for image sequences) |
| Loop · Show controls | Play in view only: start again at the end; show play, pause and the timeline |
| Hold the section | On: the video stays on screen while visitors scroll through it. Off: it plays through as it scrolls past |
| Scroll length | First frame to last, in % of the screen height (50–1000), with its own length for tablets and phones |
| Top offset | Room for a sticky header while the section is held, 0–300 px — or 0–50 vh to stop the section part-way down the screen |
| Scroll smoothing (s) | 0–3 · higher values glide to the new frame |
| Starts when the top reaches (%) · Ends when the bottom reaches (%) | Not held, or playing in view: where on the screen the effect starts and stops, 0 = top edge, 100 = bottom edge. Reset: automatic (100 / 0 when scrubbing, 90 / 10 in view) |
| Play from · Play to (% of the video) | Use only part of the video or of the frames, e.g. 20–80 |
| On phones | Same effect, or Still — the poster (or the first frame) and a normal video |
Captions
| Setting | What you can set |
|---|---|
| Captions | Add, remove, duplicate and reorder. Each has a title, text, Show from (%) and Hide at (%) of the scroll, and one of nine positions |
| Title tag | H2–H4, div or p |
Look
| Panel | What you can set |
|---|---|
| Video look | An aspect ratio instead of a height, or a height (vh or px, and a height for phones), Cover, Contain, Stretch or Natural size, border radius, a shade to help captions read |
| Caption look | Max width (px or %), distance from the edges, padding, radius, title and text size |
| Colours | Video background, shade, caption background, caption title and text |
Styles tab: font family and top/bottom margin. Wide and full width are in the toolbar.
Good to know
- The video is always muted and plays inline, which is what lets browsers scrub it without a tap.
- On iPhone and iPad the first touch on the page quietly unlocks the video so it can be scrubbed.
- A video on another site preloads whole only if that site allows cross-origin requests; otherwise the browser buffers it normally.
- In the editor the video scrubs as you scroll the canvas, but the section is never held; preview the page to see it held.
- Visitors who ask their device for reduced motion get the poster (or the first frame) and a normal video with controls, with the captions listed under it.
- An image sequence needs no special encoding and scrubs evenly in every browser, but every frame is a download: keep the count and file sizes modest, and use Load frames: as the section comes near further down a page.
- Play in view always starts muted — browsers only autoplay silent video.
Troubleshooting
- Scrubbing steps or stutters? The file needs more keyframes — see Prepare the video.
- Nothing moves on another site's URL? Check the link opens the video file itself.
- Nothing moves at all? Check Moduly is up to date — the block uses the GSAP it ships.
- A change not showing on the live site is almost always a page cache — clear your caching plugin or host cache.