react-scroll-media 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +631 -631
- package/dist/index.js.map +1 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +58 -58
package/README.md
CHANGED
|
@@ -1,632 +1,632 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# 🎬 React Scroll Media
|
|
4
|
-
|
|
5
|
-
**Production-ready, cinematic scroll sequences for React.**
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/react-scroll-media)
|
|
8
|
-
[](https://www.npmjs.com/package/react-scroll-media)
|
|
9
|
-
[](https://github.com/yourusername/react-scroll-media/blob/main/LICENSE)
|
|
11
|
-
|
|
12
|
-
*Zero scroll-jacking • Pure sticky positioning • 60fps performance*
|
|
13
|
-
|
|
14
|
-
[Installation](#-installation) • [Usage](#-usage) • [API](#%EF%B8%8F-configuration) • [Examples](#-usage)
|
|
15
|
-
|
|
16
|
-
</div>
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
## 🌟 Overview
|
|
21
|
-
|
|
22
|
-
`react-scroll-media` is a lightweight library for creating Apple-style "scrollytelling" image sequences. It maps scroll progress to image frames deterministically, using standard CSS sticky positioning for a native, jank-free feel.
|
|
23
|
-
|
|
24
|
-
<br />
|
|
25
|
-
|
|
26
|
-
<div align="center">
|
|
27
|
-
<img src="https://github.com/iam-saiteja/react-scroll-media/blob/master/demo.gif?raw=true" alt="React Scroll Media Demo" width="600" />
|
|
28
|
-
<p><em><strong>Above:</strong> A 60fps scroll-driven sequence. The animation frame is tied 1:1 to the scroll position, allowing for instant scrubbing and pausing at any angle.</em></p>
|
|
29
|
-
</div>
|
|
30
|
-
|
|
31
|
-
<br />
|
|
32
|
-
|
|
33
|
-
## ✨ Features
|
|
34
|
-
|
|
35
|
-
### 🚀 **Native Performance**
|
|
36
|
-
- Uses `requestAnimationFrame` for buttery smooth 60fps rendering
|
|
37
|
-
- **No Scroll Jacking** — We never hijack the scrollbar. It works with native scrolling
|
|
38
|
-
- **CSS Sticky** — Uses relatively positioned containers with sticky inner content
|
|
39
|
-
|
|
40
|
-
### 🖼️ **Flexible Loading**
|
|
41
|
-
- **Manual** — Pass an array of image URLs
|
|
42
|
-
- **Pattern** — Generate sequences like `/img_{index}.jpg`
|
|
43
|
-
- **Manifest** — Load sequences from a JSON manifest
|
|
44
|
-
|
|
45
|
-
### 🧠 **Smart Memory Management**
|
|
46
|
-
- **Lazy Mode** — Keeps only ±3 frames in memory for huge sequences (800+ frames)
|
|
47
|
-
- **Eager Mode** — Preloads everything for maximum smoothness on smaller sequences
|
|
48
|
-
- **Decoding** — Uses `img.decode()` to prevent main-thread jank during painting
|
|
49
|
-
|
|
50
|
-
### 🛠️ **Developer Experience**
|
|
51
|
-
- **Debug Overlay** — Visualize progress and frame index in real-time
|
|
52
|
-
- **Hooks** — Exported `useScrollSequence` for custom UI implementations
|
|
53
|
-
- **TypeScript** — First-class type definitions
|
|
54
|
-
- **SSR Safe** — Works perfectly with Next.js / Remix / Gatsby
|
|
55
|
-
- **A11y** — Built-in support for `prefers-reduced-motion` and ARIA attributes
|
|
56
|
-
- **Robust** — Error boundaries and callbacks for image load failures
|
|
57
|
-
|
|
58
|
-
<br />
|
|
59
|
-
|
|
60
|
-
---
|
|
61
|
-
|
|
62
|
-
## 🤔 When to Use This vs Video?
|
|
63
|
-
|
|
64
|
-
<table>
|
|
65
|
-
<thead>
|
|
66
|
-
<tr>
|
|
67
|
-
<th>Feature</th>
|
|
68
|
-
<th>Video (<code><video></code>)</th>
|
|
69
|
-
<th>Scroll Sequence (<code>react-scroll-media</code>)</th>
|
|
70
|
-
</tr>
|
|
71
|
-
</thead>
|
|
72
|
-
<tbody>
|
|
73
|
-
<tr>
|
|
74
|
-
<td><strong>Quality</strong></td>
|
|
75
|
-
<td>Compressed (artifacts)</td>
|
|
76
|
-
<td>✨ Lossless / Exact Frames (CRISP)</td>
|
|
77
|
-
</tr>
|
|
78
|
-
<tr>
|
|
79
|
-
<td><strong>Transparency</strong></td>
|
|
80
|
-
<td>Difficult (needs webm/hevc)</td>
|
|
81
|
-
<td>✨ Native PNG/WebP Transparency (Easy)</td>
|
|
82
|
-
</tr>
|
|
83
|
-
<tr>
|
|
84
|
-
<td><strong>Scrubbing</strong></td>
|
|
85
|
-
<td>Janky (keyframe dependency)</td>
|
|
86
|
-
<td>✨ 1:1 Instant Scrubbing</td>
|
|
87
|
-
</tr>
|
|
88
|
-
<tr>
|
|
89
|
-
<td><strong>Mobile</strong></td>
|
|
90
|
-
<td>Auto-play often blocked</td>
|
|
91
|
-
<td>✨ Works everywhere</td>
|
|
92
|
-
</tr>
|
|
93
|
-
<tr>
|
|
94
|
-
<td><strong>File Size</strong></td>
|
|
95
|
-
<td>✨ Small</td>
|
|
96
|
-
<td>Large (requires optimization/lazy loading)</td>
|
|
97
|
-
</tr>
|
|
98
|
-
</tbody>
|
|
99
|
-
</table>
|
|
100
|
-
|
|
101
|
-
**💡 Use Scroll Sequence** when you need perfect interaction, transparency, or crystal-clear product visuals (like Apple).
|
|
102
|
-
|
|
103
|
-
**💡 Use Video** for long, non-interactive backgrounds.
|
|
104
|
-
|
|
105
|
-
<br />
|
|
106
|
-
|
|
107
|
-
---
|
|
108
|
-
|
|
109
|
-
## 📦 Installation
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
npm install react-scroll-media
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
**or**
|
|
116
|
-
|
|
117
|
-
```bash
|
|
118
|
-
yarn add react-scroll-media
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
<br />
|
|
122
|
-
|
|
123
|
-
---
|
|
124
|
-
|
|
125
|
-
## 🚀 Usage
|
|
126
|
-
|
|
127
|
-
### 🎯 Basic Example
|
|
128
|
-
|
|
129
|
-
The simplest way to use it is with the `ScrollSequence` component.
|
|
130
|
-
|
|
131
|
-
```tsx
|
|
132
|
-
import { ScrollSequence } from 'react-scroll-media';
|
|
133
|
-
|
|
134
|
-
const frames = [
|
|
135
|
-
'/images/frame_01.jpg',
|
|
136
|
-
'/images/frame_02.jpg',
|
|
137
|
-
// ...
|
|
138
|
-
];
|
|
139
|
-
|
|
140
|
-
export default function MyPage() {
|
|
141
|
-
return (
|
|
142
|
-
<div style={{ height: '200vh' }}>
|
|
143
|
-
<h1>Scroll Down</h1>
|
|
144
|
-
|
|
145
|
-
<ScrollSequence
|
|
146
|
-
source={{ type: 'manual', frames }}
|
|
147
|
-
scrollLength="300vh" // Determines how long the sequence plays
|
|
148
|
-
/>
|
|
149
|
-
|
|
150
|
-
<h1>Continue Scrolling</h1>
|
|
151
|
-
</div>
|
|
152
|
-
);
|
|
153
|
-
}
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
<br />
|
|
157
|
-
|
|
158
|
-
### ✨ Scrollytelling & Composition
|
|
159
|
-
|
|
160
|
-
You can nest components inside `ScrollSequence`. They will be placed in the sticky container and can react to the timeline.
|
|
161
|
-
|
|
162
|
-
<br />
|
|
163
|
-
|
|
164
|
-
#### 📝 Animated Text (`ScrollText`)
|
|
165
|
-
|
|
166
|
-
Animate opacity and position based on scroll progress (0 to 1). Supports enter and exit phases.
|
|
167
|
-
|
|
168
|
-
```tsx
|
|
169
|
-
import { ScrollSequence, ScrollText } from 'react-scroll-media';
|
|
170
|
-
|
|
171
|
-
<ScrollSequence source={...} scrollLength="400vh">
|
|
172
|
-
|
|
173
|
-
{/* Fade In (0.1-0.2) -> Hold -> Fade Out (0.8-0.9) */}
|
|
174
|
-
<ScrollText
|
|
175
|
-
start={0.1}
|
|
176
|
-
end={0.2}
|
|
177
|
-
exitStart={0.8}
|
|
178
|
-
exitEnd={0.9}
|
|
179
|
-
translateY={50}
|
|
180
|
-
className="my-text-overlay"
|
|
181
|
-
>
|
|
182
|
-
Cinematic Experience
|
|
183
|
-
</ScrollText>
|
|
184
|
-
|
|
185
|
-
</ScrollSequence>
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
<br />
|
|
189
|
-
|
|
190
|
-
#### 💬 Word Reveal (`ScrollWordReveal`)
|
|
191
|
-
|
|
192
|
-
Reveals text word-by-word as you scroll.
|
|
193
|
-
|
|
194
|
-
```tsx
|
|
195
|
-
import { ScrollWordReveal } from 'react-scroll-media';
|
|
196
|
-
|
|
197
|
-
<ScrollWordReveal
|
|
198
|
-
text="Experience the smooth cinematic scroll."
|
|
199
|
-
start={0.4}
|
|
200
|
-
end={0.6}
|
|
201
|
-
style={{ fontSize: '2rem', color: 'white' }}
|
|
202
|
-
/>
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
<br />
|
|
206
|
-
|
|
207
|
-
### 🔧 Advanced: Custom Hooks
|
|
208
|
-
|
|
209
|
-
For full control over the specialized UI, use the headless hooks.
|
|
210
|
-
|
|
211
|
-
<br />
|
|
212
|
-
|
|
213
|
-
#### `useScrollSequence`
|
|
214
|
-
|
|
215
|
-
Manages the canvas image controller.
|
|
216
|
-
|
|
217
|
-
```tsx
|
|
218
|
-
import { useScrollSequence } from 'react-scroll-media';
|
|
219
|
-
|
|
220
|
-
const CustomScroller = () => {
|
|
221
|
-
// ... setup refs
|
|
222
|
-
const { containerRef, canvasRef, isLoaded } = useScrollSequence({ ... });
|
|
223
|
-
// ... render custom structure
|
|
224
|
-
};
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
<br />
|
|
228
|
-
|
|
229
|
-
#### `useScrollTimeline`
|
|
230
|
-
|
|
231
|
-
Subscribe to the scroll timeline in any component.
|
|
232
|
-
|
|
233
|
-
```tsx
|
|
234
|
-
import { useScrollTimeline } from 'react-scroll-media';
|
|
235
|
-
|
|
236
|
-
const MyComponent = () => {
|
|
237
|
-
const { subscribe } = useScrollTimeline();
|
|
238
|
-
|
|
239
|
-
// Subscribe to progress (0-1)
|
|
240
|
-
useEffect(() => subscribe((progress) => {
|
|
241
|
-
console.log('Progress:', progress);
|
|
242
|
-
}), [subscribe]);
|
|
243
|
-
|
|
244
|
-
return <div>...</div>;
|
|
245
|
-
};
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
<br />
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
## ⚙️ Configuration
|
|
253
|
-
|
|
254
|
-
### `ScrollSequence` Props
|
|
255
|
-
|
|
256
|
-
<table>
|
|
257
|
-
<thead>
|
|
258
|
-
<tr>
|
|
259
|
-
<th>Prop</th>
|
|
260
|
-
<th>Type</th>
|
|
261
|
-
<th>Default</th>
|
|
262
|
-
<th>Description</th>
|
|
263
|
-
</tr>
|
|
264
|
-
</thead>
|
|
265
|
-
<tbody>
|
|
266
|
-
<tr>
|
|
267
|
-
<td><code>source</code></td>
|
|
268
|
-
<td><code>SequenceSource</code></td>
|
|
269
|
-
<td><strong>Required</strong></td>
|
|
270
|
-
<td>Defines where images come from.</td>
|
|
271
|
-
</tr>
|
|
272
|
-
<tr>
|
|
273
|
-
<td><code>scrollLength</code></td>
|
|
274
|
-
<td><code>string</code></td>
|
|
275
|
-
<td><code>"300vh"</code></td>
|
|
276
|
-
<td>Height of the container (animation duration).</td>
|
|
277
|
-
</tr>
|
|
278
|
-
<tr>
|
|
279
|
-
<td><code>memoryStrategy</code></td>
|
|
280
|
-
<td><code>"eager" | "lazy"</code></td>
|
|
281
|
-
<td><code>"eager"</code></td>
|
|
282
|
-
<td>Optimization strategy.</td>
|
|
283
|
-
</tr>
|
|
284
|
-
<tr>
|
|
285
|
-
<td><code>lazyBuffer</code></td>
|
|
286
|
-
<td><code>number</code></td>
|
|
287
|
-
<td><code>10</code></td>
|
|
288
|
-
<td>Number of frames to keep loaded in lazy mode.</td>
|
|
289
|
-
</tr>
|
|
290
|
-
<tr>
|
|
291
|
-
<td><code>fallback</code></td>
|
|
292
|
-
<td><code>ReactNode</code></td>
|
|
293
|
-
<td><code>null</code></td>
|
|
294
|
-
<td>Loading state component.</td>
|
|
295
|
-
</tr>
|
|
296
|
-
<tr>
|
|
297
|
-
<td><code>accessibilityLabel</code></td>
|
|
298
|
-
<td><code>string</code></td>
|
|
299
|
-
<td><code>"Scroll sequence"</code></td>
|
|
300
|
-
<td>ARIA label for the canvas. Example: <code>"360 degree view of the product"</code>.</td>
|
|
301
|
-
</tr>
|
|
302
|
-
<tr>
|
|
303
|
-
<td><code>debug</code></td>
|
|
304
|
-
<td><code>boolean</code></td>
|
|
305
|
-
<td><code>false</code></td>
|
|
306
|
-
<td>Shows debug overlay.</td>
|
|
307
|
-
</tr>
|
|
308
|
-
<tr>
|
|
309
|
-
<td><code>onError</code></td>
|
|
310
|
-
<td><code>(error: Error) => void</code></td>
|
|
311
|
-
<td><code>undefined</code></td>
|
|
312
|
-
<td>Callback fired when an image fails to load or initialization errors occur.</td>
|
|
313
|
-
</tr>
|
|
314
|
-
</tbody>
|
|
315
|
-
</table>
|
|
316
|
-
|
|
317
|
-
<br />
|
|
318
|
-
|
|
319
|
-
---
|
|
320
|
-
|
|
321
|
-
## 📊 Performance & Compatibility
|
|
322
|
-
|
|
323
|
-
### 📦 Bundle Size
|
|
324
|
-
|
|
325
|
-
| Metric | Size |
|
|
326
|
-
|--------|------|
|
|
327
|
-
| **Minified** | ~22.0 kB |
|
|
328
|
-
| **Gzipped** | ~6.08 kB |
|
|
329
|
-
|
|
330
|
-
✨ **Zero dependencies** — Uses native Canvas API, no heavyweight libraries.
|
|
331
|
-
|
|
332
|
-
<br />
|
|
333
|
-
|
|
334
|
-
### 🌐 Browser Support
|
|
335
|
-
|
|
336
|
-
<table>
|
|
337
|
-
<thead>
|
|
338
|
-
<tr>
|
|
339
|
-
<th>Browser</th>
|
|
340
|
-
<th>Status</th>
|
|
341
|
-
<th>Note</th>
|
|
342
|
-
</tr>
|
|
343
|
-
</thead>
|
|
344
|
-
<tbody>
|
|
345
|
-
<tr>
|
|
346
|
-
<td>Chrome</td>
|
|
347
|
-
<td>✅</td>
|
|
348
|
-
<td>Full support (OffscreenCanvas enabled)</td>
|
|
349
|
-
</tr>
|
|
350
|
-
<tr>
|
|
351
|
-
<td>Firefox</td>
|
|
352
|
-
<td>✅</td>
|
|
353
|
-
<td>Full support</td>
|
|
354
|
-
</tr>
|
|
355
|
-
<tr>
|
|
356
|
-
<td>Safari</td>
|
|
357
|
-
<td>✅</td>
|
|
358
|
-
<td>Full support (Desktop & Mobile)</td>
|
|
359
|
-
</tr>
|
|
360
|
-
<tr>
|
|
361
|
-
<td>Edge</td>
|
|
362
|
-
<td>✅</td>
|
|
363
|
-
<td>Full support</td>
|
|
364
|
-
</tr>
|
|
365
|
-
<tr>
|
|
366
|
-
<td>IE11</td>
|
|
367
|
-
<td>❌</td>
|
|
368
|
-
<td>Not supported (Missing ES6/Canvas features)</td>
|
|
369
|
-
</tr>
|
|
370
|
-
</tbody>
|
|
371
|
-
</table>
|
|
372
|
-
|
|
373
|
-
<br />
|
|
374
|
-
|
|
375
|
-
### ♿ Accessibility (A11y)
|
|
376
|
-
|
|
377
|
-
- **🎹 Keyboard Navigation** — Users can scrub through the sequence using standard keyboard controls (Arrow Keys, Spacebar, Page Up/Down) because it relies on native scrolling.
|
|
378
|
-
|
|
379
|
-
- **🔊 Screen Readers** — Add `accessibilityLabel` to `ScrollSequence` to provide a description for the canvas. Canvas has `role="img"`.
|
|
380
|
-
|
|
381
|
-
- **🎭 Reduced Motion** — Automatically detects `prefers-reduced-motion: reduce`. If enabled, `ScrollSequence` will disable the scroll animation and display the `fallback` content (if provided) or simply freeze the first frame to prevent motion sickness.
|
|
382
|
-
|
|
383
|
-
<br />
|
|
384
|
-
|
|
385
|
-
### 💾 Memory Usage (Benchmarks)
|
|
386
|
-
|
|
387
|
-
*Tested on 1080p frames.*
|
|
388
|
-
|
|
389
|
-
<table>
|
|
390
|
-
<thead>
|
|
391
|
-
<tr>
|
|
392
|
-
<th>Frames</th>
|
|
393
|
-
<th>Strategy</th>
|
|
394
|
-
<th>Memory</th>
|
|
395
|
-
<th>Recommendation</th>
|
|
396
|
-
</tr>
|
|
397
|
-
</thead>
|
|
398
|
-
<tbody>
|
|
399
|
-
<tr>
|
|
400
|
-
<td>100</td>
|
|
401
|
-
<td><code>eager</code></td>
|
|
402
|
-
<td>30MB</td>
|
|
403
|
-
<td>Instant seeking, smooth.</td>
|
|
404
|
-
</tr>
|
|
405
|
-
<tr>
|
|
406
|
-
<td>500</td>
|
|
407
|
-
<td><code>eager</code></td>
|
|
408
|
-
<td>46MB</td>
|
|
409
|
-
<td>High RAM usage.</td>
|
|
410
|
-
</tr>
|
|
411
|
-
<tr>
|
|
412
|
-
<td>1000</td>
|
|
413
|
-
<td><code>eager</code></td>
|
|
414
|
-
<td>57MB</td>
|
|
415
|
-
<td>Very high RAM usage.</td>
|
|
416
|
-
</tr>
|
|
417
|
-
<tr>
|
|
418
|
-
<td>100</td>
|
|
419
|
-
<td><code>lazy</code></td>
|
|
420
|
-
<td>25MB</td>
|
|
421
|
-
<td>Low memory usage.</td>
|
|
422
|
-
</tr>
|
|
423
|
-
<tr>
|
|
424
|
-
<td>500</td>
|
|
425
|
-
<td><code>lazy</code></td>
|
|
426
|
-
<td>30MB</td>
|
|
427
|
-
<td>Low memory usage.</td>
|
|
428
|
-
</tr>
|
|
429
|
-
<tr>
|
|
430
|
-
<td>1000</td>
|
|
431
|
-
<td><code>lazy</code></td>
|
|
432
|
-
<td>45MB</td>
|
|
433
|
-
<td><strong>⭐ Recommended</strong>. Kept flat constant.</td>
|
|
434
|
-
</tr>
|
|
435
|
-
</tbody>
|
|
436
|
-
</table>
|
|
437
|
-
|
|
438
|
-
<br />
|
|
439
|
-
|
|
440
|
-
### 🛡️ Error Handling & Fallbacks
|
|
441
|
-
|
|
442
|
-
Network errors are handled gracefully. You can provide a fallback UI that displays while images are loading or if they fail.
|
|
443
|
-
|
|
444
|
-
```tsx
|
|
445
|
-
<ScrollSequence
|
|
446
|
-
source={{ type: 'manifest', url: '/bad_url.json' }}
|
|
447
|
-
fallback={<div className="error">Failed to load sequence</div>}
|
|
448
|
-
onError={(e) => console.error("Sequence error:", e)}
|
|
449
|
-
/>
|
|
450
|
-
```
|
|
451
|
-
|
|
452
|
-
<br />
|
|
453
|
-
|
|
454
|
-
### 🚨 Error Boundaries
|
|
455
|
-
|
|
456
|
-
For robust production apps, wrap `ScrollSequence` in an Error Boundary to catch unexpected crashes:
|
|
457
|
-
|
|
458
|
-
```tsx
|
|
459
|
-
class ErrorBoundary extends React.Component<
|
|
460
|
-
{ fallback: React.ReactNode, children: React.ReactNode },
|
|
461
|
-
{ hasError: boolean }
|
|
462
|
-
> {
|
|
463
|
-
state = { hasError: false };
|
|
464
|
-
|
|
465
|
-
static getDerivedStateFromError() {
|
|
466
|
-
return { hasError: true };
|
|
467
|
-
}
|
|
468
|
-
|
|
469
|
-
render() {
|
|
470
|
-
if (this.state.hasError) return this.props.fallback;
|
|
471
|
-
return this.props.children;
|
|
472
|
-
}
|
|
473
|
-
}
|
|
474
|
-
|
|
475
|
-
// Usage
|
|
476
|
-
<ErrorBoundary fallback={<div>Something went wrong</div>}>
|
|
477
|
-
<ScrollSequence source={...} />
|
|
478
|
-
</ErrorBoundary>
|
|
479
|
-
```
|
|
480
|
-
|
|
481
|
-
<br />
|
|
482
|
-
|
|
483
|
-
### 🔄 Multi-Instance & Nested Scroll
|
|
484
|
-
|
|
485
|
-
`react-scroll-media` automatically handles multiple instances on the same page. Each instance:
|
|
486
|
-
|
|
487
|
-
1. Registers with a shared `RAF` loop (singleton) for optimal performance.
|
|
488
|
-
2. Calculates its own progress independently.
|
|
489
|
-
3. Should have a unique `scrollLength` or container setup.
|
|
490
|
-
|
|
491
|
-
<br />
|
|
492
|
-
|
|
493
|
-
---
|
|
494
|
-
|
|
495
|
-
## 🏗️ Architecture
|
|
496
|
-
|
|
497
|
-
### 📂 `SequenceSource` Options
|
|
498
|
-
|
|
499
|
-
<br />
|
|
500
|
-
|
|
501
|
-
#### **1. Manual Mode** (Pass array directly)
|
|
502
|
-
|
|
503
|
-
```ts
|
|
504
|
-
{
|
|
505
|
-
type: 'manual',
|
|
506
|
-
frames: ['/img/1.jpg', '/img/2.jpg']
|
|
507
|
-
}
|
|
508
|
-
```
|
|
509
|
-
|
|
510
|
-
<br />
|
|
511
|
-
|
|
512
|
-
#### **2. Pattern Mode** (Generate URLs)
|
|
513
|
-
|
|
514
|
-
```ts
|
|
515
|
-
{
|
|
516
|
-
type: 'pattern',
|
|
517
|
-
url: '/assets/sequence_{index}.jpg', // {index} is replaced
|
|
518
|
-
start: 1, // Start index
|
|
519
|
-
end: 100, // End index
|
|
520
|
-
pad: 4 // Zero padding (e.g. 1 -> 0001)
|
|
521
|
-
}
|
|
522
|
-
```
|
|
523
|
-
|
|
524
|
-
<br />
|
|
525
|
-
|
|
526
|
-
#### **3. Manifest Mode** (Fetch JSON)
|
|
527
|
-
|
|
528
|
-
```ts
|
|
529
|
-
{
|
|
530
|
-
type: 'manifest',
|
|
531
|
-
url: '/sequence.json'
|
|
532
|
-
}
|
|
533
|
-
|
|
534
|
-
// JSON format: { "frames": ["url1", "url2"] } OR pattern config
|
|
535
|
-
```
|
|
536
|
-
|
|
537
|
-
> **💡 Note**: Manifests are cached in memory by URL. To force a refresh, append a query param (e.g. `?v=2`).
|
|
538
|
-
|
|
539
|
-
<br />
|
|
540
|
-
|
|
541
|
-
---
|
|
542
|
-
|
|
543
|
-
## 🎨 How it Works (The "Sticky" Technique)
|
|
544
|
-
|
|
545
|
-
Unlike libraries that use `position: fixed` or JS-based scroll locking (which breaks refreshing and feels unnatural), we use **CSS Sticky Positioning**.
|
|
546
|
-
|
|
547
|
-
<br />
|
|
548
|
-
|
|
549
|
-
<div align="center">
|
|
550
|
-
<img src="https://github.com/iam-saiteja/react-scroll-media/blob/master/demo-213.gif?raw=true" alt="React Scroll Media Technical Demo" width="600" />
|
|
551
|
-
<p><em><strong>Technical Demo:</strong> This visualization shows the direct correlation between the scrollbar position and the rendered frame. The component calculates the exact frame index based on the percentage of the container scrolled, ensuring perfect synchronization without "scroll jacking".</em></p>
|
|
552
|
-
</div>
|
|
553
|
-
|
|
554
|
-
<br />
|
|
555
|
-
|
|
556
|
-
### 🔧 Technical Breakdown
|
|
557
|
-
|
|
558
|
-
1. **Container (`relative`)** — This element has the height you specify (e.g., `300vh`). It occupies space in the document flow.
|
|
559
|
-
|
|
560
|
-
2. **Sticky Wrapper (`sticky`)** — Inside the container, we place a `div` that is `100vh` tall and `sticky` at `top: 0`.
|
|
561
|
-
|
|
562
|
-
3. **Canvas** — The `<canvas>` sits inside the sticky wrapper.
|
|
563
|
-
|
|
564
|
-
4. **Math** — As you scroll the container, the sticky wrapper stays pinned to the viewport. We calculate:
|
|
565
|
-
|
|
566
|
-
```ts
|
|
567
|
-
progress = -containerRect.top / (containerHeight - viewportHeight)
|
|
568
|
-
```
|
|
569
|
-
|
|
570
|
-
This gives a precise **0.0 to 1.0** value tied to the pixel position of the scrollbar. This value is then mapped to the corresponding frame index:
|
|
571
|
-
|
|
572
|
-
```ts
|
|
573
|
-
frameIndex = Math.floor(progress * (totalFrames - 1))
|
|
574
|
-
```
|
|
575
|
-
|
|
576
|
-
This approach ensures:
|
|
577
|
-
* **Zero Jitter**: The canvas position is handled by the browser's compositor thread (CSS Sticky).
|
|
578
|
-
* **Native Feel**: Momentum scrolling works perfectly on touchpads and mobile.
|
|
579
|
-
* **Exact Sync**: The frame updates are synchronized with the scroll position in a `requestAnimationFrame` loop.
|
|
580
|
-
|
|
581
|
-
<br />
|
|
582
|
-
|
|
583
|
-
### 💡 Memory Strategy
|
|
584
|
-
|
|
585
|
-
- **"eager" (Default)** — Best for sequences < 200 frames. Preloads all images into `HTMLImageElement` instances. Instant seeking, smooth playback. High memory usage.
|
|
586
|
-
|
|
587
|
-
- **"lazy"** — Best for long sequences (500+ frames). Only keeps the current frame and its neighbors in memory. Saves RAM, prevents crashes.
|
|
588
|
-
- Buffer size defaults to ±10 frames but can be customized via `lazyBuffer`.
|
|
589
|
-
|
|
590
|
-
<br />
|
|
591
|
-
|
|
592
|
-
---
|
|
593
|
-
|
|
594
|
-
## 🐛 Debugging
|
|
595
|
-
|
|
596
|
-
Enable the debug overlay to inspect your sequence in production:
|
|
597
|
-
|
|
598
|
-
```tsx
|
|
599
|
-
<ScrollSequence
|
|
600
|
-
source={...}
|
|
601
|
-
debug={true}
|
|
602
|
-
/>
|
|
603
|
-
```
|
|
604
|
-
|
|
605
|
-
<br />
|
|
606
|
-
|
|
607
|
-
**Output:**
|
|
608
|
-
|
|
609
|
-
```
|
|
610
|
-
Progress: 0.45
|
|
611
|
-
Frame: 45 / 100
|
|
612
|
-
```
|
|
613
|
-
|
|
614
|
-
This overlay is updated directly via DOM manipulation (bypassing React renders) for **zero overhead**.
|
|
615
|
-
|
|
616
|
-
<br />
|
|
617
|
-
|
|
618
|
-
---
|
|
619
|
-
|
|
620
|
-
<div align="center">
|
|
621
|
-
|
|
622
|
-
## 📄 License
|
|
623
|
-
|
|
624
|
-
**MIT** © 2026 **Thanniru Sai Teja**
|
|
625
|
-
|
|
626
|
-
<br />
|
|
627
|
-
|
|
628
|
-
Made with ❤️ for the React community
|
|
629
|
-
|
|
630
|
-
[⬆ Back to Top](#-react-scroll-media)
|
|
631
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# 🎬 React Scroll Media
|
|
4
|
+
|
|
5
|
+
**Production-ready, cinematic scroll sequences for React.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/react-scroll-media)
|
|
8
|
+
[](https://www.npmjs.com/package/react-scroll-media)
|
|
9
|
+
[](https://packagephobia.com/result?p=react-scroll-media)
|
|
10
|
+
[](https://github.com/yourusername/react-scroll-media/blob/main/LICENSE)
|
|
11
|
+
|
|
12
|
+
*Zero scroll-jacking • Pure sticky positioning • 60fps performance*
|
|
13
|
+
|
|
14
|
+
[Installation](#-installation) • [Usage](#-usage) • [API](#%EF%B8%8F-configuration) • [Examples](#-usage)
|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 🌟 Overview
|
|
21
|
+
|
|
22
|
+
`react-scroll-media` is a lightweight library for creating Apple-style "scrollytelling" image sequences. It maps scroll progress to image frames deterministically, using standard CSS sticky positioning for a native, jank-free feel.
|
|
23
|
+
|
|
24
|
+
<br />
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
<img src="https://github.com/iam-saiteja/react-scroll-media/blob/master/demo.gif?raw=true" alt="React Scroll Media Demo" width="600" />
|
|
28
|
+
<p><em><strong>Above:</strong> A 60fps scroll-driven sequence. The animation frame is tied 1:1 to the scroll position, allowing for instant scrubbing and pausing at any angle.</em></p>
|
|
29
|
+
</div>
|
|
30
|
+
|
|
31
|
+
<br />
|
|
32
|
+
|
|
33
|
+
## ✨ Features
|
|
34
|
+
|
|
35
|
+
### 🚀 **Native Performance**
|
|
36
|
+
- Uses `requestAnimationFrame` for buttery smooth 60fps rendering
|
|
37
|
+
- **No Scroll Jacking** — We never hijack the scrollbar. It works with native scrolling
|
|
38
|
+
- **CSS Sticky** — Uses relatively positioned containers with sticky inner content
|
|
39
|
+
|
|
40
|
+
### 🖼️ **Flexible Loading**
|
|
41
|
+
- **Manual** — Pass an array of image URLs
|
|
42
|
+
- **Pattern** — Generate sequences like `/img_{index}.jpg`
|
|
43
|
+
- **Manifest** — Load sequences from a JSON manifest
|
|
44
|
+
|
|
45
|
+
### 🧠 **Smart Memory Management**
|
|
46
|
+
- **Lazy Mode** — Keeps only ±3 frames in memory for huge sequences (800+ frames)
|
|
47
|
+
- **Eager Mode** — Preloads everything for maximum smoothness on smaller sequences
|
|
48
|
+
- **Decoding** — Uses `img.decode()` to prevent main-thread jank during painting
|
|
49
|
+
|
|
50
|
+
### 🛠️ **Developer Experience**
|
|
51
|
+
- **Debug Overlay** — Visualize progress and frame index in real-time
|
|
52
|
+
- **Hooks** — Exported `useScrollSequence` for custom UI implementations
|
|
53
|
+
- **TypeScript** — First-class type definitions
|
|
54
|
+
- **SSR Safe** — Works perfectly with Next.js / Remix / Gatsby
|
|
55
|
+
- **A11y** — Built-in support for `prefers-reduced-motion` and ARIA attributes
|
|
56
|
+
- **Robust** — Error boundaries and callbacks for image load failures
|
|
57
|
+
|
|
58
|
+
<br />
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 🤔 When to Use This vs Video?
|
|
63
|
+
|
|
64
|
+
<table>
|
|
65
|
+
<thead>
|
|
66
|
+
<tr>
|
|
67
|
+
<th>Feature</th>
|
|
68
|
+
<th>Video (<code><video></code>)</th>
|
|
69
|
+
<th>Scroll Sequence (<code>react-scroll-media</code>)</th>
|
|
70
|
+
</tr>
|
|
71
|
+
</thead>
|
|
72
|
+
<tbody>
|
|
73
|
+
<tr>
|
|
74
|
+
<td><strong>Quality</strong></td>
|
|
75
|
+
<td>Compressed (artifacts)</td>
|
|
76
|
+
<td>✨ Lossless / Exact Frames (CRISP)</td>
|
|
77
|
+
</tr>
|
|
78
|
+
<tr>
|
|
79
|
+
<td><strong>Transparency</strong></td>
|
|
80
|
+
<td>Difficult (needs webm/hevc)</td>
|
|
81
|
+
<td>✨ Native PNG/WebP Transparency (Easy)</td>
|
|
82
|
+
</tr>
|
|
83
|
+
<tr>
|
|
84
|
+
<td><strong>Scrubbing</strong></td>
|
|
85
|
+
<td>Janky (keyframe dependency)</td>
|
|
86
|
+
<td>✨ 1:1 Instant Scrubbing</td>
|
|
87
|
+
</tr>
|
|
88
|
+
<tr>
|
|
89
|
+
<td><strong>Mobile</strong></td>
|
|
90
|
+
<td>Auto-play often blocked</td>
|
|
91
|
+
<td>✨ Works everywhere</td>
|
|
92
|
+
</tr>
|
|
93
|
+
<tr>
|
|
94
|
+
<td><strong>File Size</strong></td>
|
|
95
|
+
<td>✨ Small</td>
|
|
96
|
+
<td>Large (requires optimization/lazy loading)</td>
|
|
97
|
+
</tr>
|
|
98
|
+
</tbody>
|
|
99
|
+
</table>
|
|
100
|
+
|
|
101
|
+
**💡 Use Scroll Sequence** when you need perfect interaction, transparency, or crystal-clear product visuals (like Apple).
|
|
102
|
+
|
|
103
|
+
**💡 Use Video** for long, non-interactive backgrounds.
|
|
104
|
+
|
|
105
|
+
<br />
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 📦 Installation
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
npm install react-scroll-media
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**or**
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
yarn add react-scroll-media
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
<br />
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 🚀 Usage
|
|
126
|
+
|
|
127
|
+
### 🎯 Basic Example
|
|
128
|
+
|
|
129
|
+
The simplest way to use it is with the `ScrollSequence` component.
|
|
130
|
+
|
|
131
|
+
```tsx
|
|
132
|
+
import { ScrollSequence } from 'react-scroll-media';
|
|
133
|
+
|
|
134
|
+
const frames = [
|
|
135
|
+
'/images/frame_01.jpg',
|
|
136
|
+
'/images/frame_02.jpg',
|
|
137
|
+
// ...
|
|
138
|
+
];
|
|
139
|
+
|
|
140
|
+
export default function MyPage() {
|
|
141
|
+
return (
|
|
142
|
+
<div style={{ height: '200vh' }}>
|
|
143
|
+
<h1>Scroll Down</h1>
|
|
144
|
+
|
|
145
|
+
<ScrollSequence
|
|
146
|
+
source={{ type: 'manual', frames }}
|
|
147
|
+
scrollLength="300vh" // Determines how long the sequence plays
|
|
148
|
+
/>
|
|
149
|
+
|
|
150
|
+
<h1>Continue Scrolling</h1>
|
|
151
|
+
</div>
|
|
152
|
+
);
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
<br />
|
|
157
|
+
|
|
158
|
+
### ✨ Scrollytelling & Composition
|
|
159
|
+
|
|
160
|
+
You can nest components inside `ScrollSequence`. They will be placed in the sticky container and can react to the timeline.
|
|
161
|
+
|
|
162
|
+
<br />
|
|
163
|
+
|
|
164
|
+
#### 📝 Animated Text (`ScrollText`)
|
|
165
|
+
|
|
166
|
+
Animate opacity and position based on scroll progress (0 to 1). Supports enter and exit phases.
|
|
167
|
+
|
|
168
|
+
```tsx
|
|
169
|
+
import { ScrollSequence, ScrollText } from 'react-scroll-media';
|
|
170
|
+
|
|
171
|
+
<ScrollSequence source={...} scrollLength="400vh">
|
|
172
|
+
|
|
173
|
+
{/* Fade In (0.1-0.2) -> Hold -> Fade Out (0.8-0.9) */}
|
|
174
|
+
<ScrollText
|
|
175
|
+
start={0.1}
|
|
176
|
+
end={0.2}
|
|
177
|
+
exitStart={0.8}
|
|
178
|
+
exitEnd={0.9}
|
|
179
|
+
translateY={50}
|
|
180
|
+
className="my-text-overlay"
|
|
181
|
+
>
|
|
182
|
+
Cinematic Experience
|
|
183
|
+
</ScrollText>
|
|
184
|
+
|
|
185
|
+
</ScrollSequence>
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
<br />
|
|
189
|
+
|
|
190
|
+
#### 💬 Word Reveal (`ScrollWordReveal`)
|
|
191
|
+
|
|
192
|
+
Reveals text word-by-word as you scroll.
|
|
193
|
+
|
|
194
|
+
```tsx
|
|
195
|
+
import { ScrollWordReveal } from 'react-scroll-media';
|
|
196
|
+
|
|
197
|
+
<ScrollWordReveal
|
|
198
|
+
text="Experience the smooth cinematic scroll."
|
|
199
|
+
start={0.4}
|
|
200
|
+
end={0.6}
|
|
201
|
+
style={{ fontSize: '2rem', color: 'white' }}
|
|
202
|
+
/>
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
<br />
|
|
206
|
+
|
|
207
|
+
### 🔧 Advanced: Custom Hooks
|
|
208
|
+
|
|
209
|
+
For full control over the specialized UI, use the headless hooks.
|
|
210
|
+
|
|
211
|
+
<br />
|
|
212
|
+
|
|
213
|
+
#### `useScrollSequence`
|
|
214
|
+
|
|
215
|
+
Manages the canvas image controller.
|
|
216
|
+
|
|
217
|
+
```tsx
|
|
218
|
+
import { useScrollSequence } from 'react-scroll-media';
|
|
219
|
+
|
|
220
|
+
const CustomScroller = () => {
|
|
221
|
+
// ... setup refs
|
|
222
|
+
const { containerRef, canvasRef, isLoaded } = useScrollSequence({ ... });
|
|
223
|
+
// ... render custom structure
|
|
224
|
+
};
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
<br />
|
|
228
|
+
|
|
229
|
+
#### `useScrollTimeline`
|
|
230
|
+
|
|
231
|
+
Subscribe to the scroll timeline in any component.
|
|
232
|
+
|
|
233
|
+
```tsx
|
|
234
|
+
import { useScrollTimeline } from 'react-scroll-media';
|
|
235
|
+
|
|
236
|
+
const MyComponent = () => {
|
|
237
|
+
const { subscribe } = useScrollTimeline();
|
|
238
|
+
|
|
239
|
+
// Subscribe to progress (0-1)
|
|
240
|
+
useEffect(() => subscribe((progress) => {
|
|
241
|
+
console.log('Progress:', progress);
|
|
242
|
+
}), [subscribe]);
|
|
243
|
+
|
|
244
|
+
return <div>...</div>;
|
|
245
|
+
};
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
<br />
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## ⚙️ Configuration
|
|
253
|
+
|
|
254
|
+
### `ScrollSequence` Props
|
|
255
|
+
|
|
256
|
+
<table>
|
|
257
|
+
<thead>
|
|
258
|
+
<tr>
|
|
259
|
+
<th>Prop</th>
|
|
260
|
+
<th>Type</th>
|
|
261
|
+
<th>Default</th>
|
|
262
|
+
<th>Description</th>
|
|
263
|
+
</tr>
|
|
264
|
+
</thead>
|
|
265
|
+
<tbody>
|
|
266
|
+
<tr>
|
|
267
|
+
<td><code>source</code></td>
|
|
268
|
+
<td><code>SequenceSource</code></td>
|
|
269
|
+
<td><strong>Required</strong></td>
|
|
270
|
+
<td>Defines where images come from.</td>
|
|
271
|
+
</tr>
|
|
272
|
+
<tr>
|
|
273
|
+
<td><code>scrollLength</code></td>
|
|
274
|
+
<td><code>string</code></td>
|
|
275
|
+
<td><code>"300vh"</code></td>
|
|
276
|
+
<td>Height of the container (animation duration).</td>
|
|
277
|
+
</tr>
|
|
278
|
+
<tr>
|
|
279
|
+
<td><code>memoryStrategy</code></td>
|
|
280
|
+
<td><code>"eager" | "lazy"</code></td>
|
|
281
|
+
<td><code>"eager"</code></td>
|
|
282
|
+
<td>Optimization strategy.</td>
|
|
283
|
+
</tr>
|
|
284
|
+
<tr>
|
|
285
|
+
<td><code>lazyBuffer</code></td>
|
|
286
|
+
<td><code>number</code></td>
|
|
287
|
+
<td><code>10</code></td>
|
|
288
|
+
<td>Number of frames to keep loaded in lazy mode.</td>
|
|
289
|
+
</tr>
|
|
290
|
+
<tr>
|
|
291
|
+
<td><code>fallback</code></td>
|
|
292
|
+
<td><code>ReactNode</code></td>
|
|
293
|
+
<td><code>null</code></td>
|
|
294
|
+
<td>Loading state component.</td>
|
|
295
|
+
</tr>
|
|
296
|
+
<tr>
|
|
297
|
+
<td><code>accessibilityLabel</code></td>
|
|
298
|
+
<td><code>string</code></td>
|
|
299
|
+
<td><code>"Scroll sequence"</code></td>
|
|
300
|
+
<td>ARIA label for the canvas. Example: <code>"360 degree view of the product"</code>.</td>
|
|
301
|
+
</tr>
|
|
302
|
+
<tr>
|
|
303
|
+
<td><code>debug</code></td>
|
|
304
|
+
<td><code>boolean</code></td>
|
|
305
|
+
<td><code>false</code></td>
|
|
306
|
+
<td>Shows debug overlay.</td>
|
|
307
|
+
</tr>
|
|
308
|
+
<tr>
|
|
309
|
+
<td><code>onError</code></td>
|
|
310
|
+
<td><code>(error: Error) => void</code></td>
|
|
311
|
+
<td><code>undefined</code></td>
|
|
312
|
+
<td>Callback fired when an image fails to load or initialization errors occur.</td>
|
|
313
|
+
</tr>
|
|
314
|
+
</tbody>
|
|
315
|
+
</table>
|
|
316
|
+
|
|
317
|
+
<br />
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## 📊 Performance & Compatibility
|
|
322
|
+
|
|
323
|
+
### 📦 Bundle Size
|
|
324
|
+
|
|
325
|
+
| Metric | Size |
|
|
326
|
+
|--------|------|
|
|
327
|
+
| **Minified** | ~22.0 kB |
|
|
328
|
+
| **Gzipped** | ~6.08 kB |
|
|
329
|
+
|
|
330
|
+
✨ **Zero dependencies** — Uses native Canvas API, no heavyweight libraries.
|
|
331
|
+
|
|
332
|
+
<br />
|
|
333
|
+
|
|
334
|
+
### 🌐 Browser Support
|
|
335
|
+
|
|
336
|
+
<table>
|
|
337
|
+
<thead>
|
|
338
|
+
<tr>
|
|
339
|
+
<th>Browser</th>
|
|
340
|
+
<th>Status</th>
|
|
341
|
+
<th>Note</th>
|
|
342
|
+
</tr>
|
|
343
|
+
</thead>
|
|
344
|
+
<tbody>
|
|
345
|
+
<tr>
|
|
346
|
+
<td>Chrome</td>
|
|
347
|
+
<td>✅</td>
|
|
348
|
+
<td>Full support (OffscreenCanvas enabled)</td>
|
|
349
|
+
</tr>
|
|
350
|
+
<tr>
|
|
351
|
+
<td>Firefox</td>
|
|
352
|
+
<td>✅</td>
|
|
353
|
+
<td>Full support</td>
|
|
354
|
+
</tr>
|
|
355
|
+
<tr>
|
|
356
|
+
<td>Safari</td>
|
|
357
|
+
<td>✅</td>
|
|
358
|
+
<td>Full support (Desktop & Mobile)</td>
|
|
359
|
+
</tr>
|
|
360
|
+
<tr>
|
|
361
|
+
<td>Edge</td>
|
|
362
|
+
<td>✅</td>
|
|
363
|
+
<td>Full support</td>
|
|
364
|
+
</tr>
|
|
365
|
+
<tr>
|
|
366
|
+
<td>IE11</td>
|
|
367
|
+
<td>❌</td>
|
|
368
|
+
<td>Not supported (Missing ES6/Canvas features)</td>
|
|
369
|
+
</tr>
|
|
370
|
+
</tbody>
|
|
371
|
+
</table>
|
|
372
|
+
|
|
373
|
+
<br />
|
|
374
|
+
|
|
375
|
+
### ♿ Accessibility (A11y)
|
|
376
|
+
|
|
377
|
+
- **🎹 Keyboard Navigation** — Users can scrub through the sequence using standard keyboard controls (Arrow Keys, Spacebar, Page Up/Down) because it relies on native scrolling.
|
|
378
|
+
|
|
379
|
+
- **🔊 Screen Readers** — Add `accessibilityLabel` to `ScrollSequence` to provide a description for the canvas. Canvas has `role="img"`.
|
|
380
|
+
|
|
381
|
+
- **🎭 Reduced Motion** — Automatically detects `prefers-reduced-motion: reduce`. If enabled, `ScrollSequence` will disable the scroll animation and display the `fallback` content (if provided) or simply freeze the first frame to prevent motion sickness.
|
|
382
|
+
|
|
383
|
+
<br />
|
|
384
|
+
|
|
385
|
+
### 💾 Memory Usage (Benchmarks)
|
|
386
|
+
|
|
387
|
+
*Tested on 1080p frames.*
|
|
388
|
+
|
|
389
|
+
<table>
|
|
390
|
+
<thead>
|
|
391
|
+
<tr>
|
|
392
|
+
<th>Frames</th>
|
|
393
|
+
<th>Strategy</th>
|
|
394
|
+
<th>Memory</th>
|
|
395
|
+
<th>Recommendation</th>
|
|
396
|
+
</tr>
|
|
397
|
+
</thead>
|
|
398
|
+
<tbody>
|
|
399
|
+
<tr>
|
|
400
|
+
<td>100</td>
|
|
401
|
+
<td><code>eager</code></td>
|
|
402
|
+
<td>30MB</td>
|
|
403
|
+
<td>Instant seeking, smooth.</td>
|
|
404
|
+
</tr>
|
|
405
|
+
<tr>
|
|
406
|
+
<td>500</td>
|
|
407
|
+
<td><code>eager</code></td>
|
|
408
|
+
<td>46MB</td>
|
|
409
|
+
<td>High RAM usage.</td>
|
|
410
|
+
</tr>
|
|
411
|
+
<tr>
|
|
412
|
+
<td>1000</td>
|
|
413
|
+
<td><code>eager</code></td>
|
|
414
|
+
<td>57MB</td>
|
|
415
|
+
<td>Very high RAM usage.</td>
|
|
416
|
+
</tr>
|
|
417
|
+
<tr>
|
|
418
|
+
<td>100</td>
|
|
419
|
+
<td><code>lazy</code></td>
|
|
420
|
+
<td>25MB</td>
|
|
421
|
+
<td>Low memory usage.</td>
|
|
422
|
+
</tr>
|
|
423
|
+
<tr>
|
|
424
|
+
<td>500</td>
|
|
425
|
+
<td><code>lazy</code></td>
|
|
426
|
+
<td>30MB</td>
|
|
427
|
+
<td>Low memory usage.</td>
|
|
428
|
+
</tr>
|
|
429
|
+
<tr>
|
|
430
|
+
<td>1000</td>
|
|
431
|
+
<td><code>lazy</code></td>
|
|
432
|
+
<td>45MB</td>
|
|
433
|
+
<td><strong>⭐ Recommended</strong>. Kept flat constant.</td>
|
|
434
|
+
</tr>
|
|
435
|
+
</tbody>
|
|
436
|
+
</table>
|
|
437
|
+
|
|
438
|
+
<br />
|
|
439
|
+
|
|
440
|
+
### 🛡️ Error Handling & Fallbacks
|
|
441
|
+
|
|
442
|
+
Network errors are handled gracefully. You can provide a fallback UI that displays while images are loading or if they fail.
|
|
443
|
+
|
|
444
|
+
```tsx
|
|
445
|
+
<ScrollSequence
|
|
446
|
+
source={{ type: 'manifest', url: '/bad_url.json' }}
|
|
447
|
+
fallback={<div className="error">Failed to load sequence</div>}
|
|
448
|
+
onError={(e) => console.error("Sequence error:", e)}
|
|
449
|
+
/>
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
<br />
|
|
453
|
+
|
|
454
|
+
### 🚨 Error Boundaries
|
|
455
|
+
|
|
456
|
+
For robust production apps, wrap `ScrollSequence` in an Error Boundary to catch unexpected crashes:
|
|
457
|
+
|
|
458
|
+
```tsx
|
|
459
|
+
class ErrorBoundary extends React.Component<
|
|
460
|
+
{ fallback: React.ReactNode, children: React.ReactNode },
|
|
461
|
+
{ hasError: boolean }
|
|
462
|
+
> {
|
|
463
|
+
state = { hasError: false };
|
|
464
|
+
|
|
465
|
+
static getDerivedStateFromError() {
|
|
466
|
+
return { hasError: true };
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
render() {
|
|
470
|
+
if (this.state.hasError) return this.props.fallback;
|
|
471
|
+
return this.props.children;
|
|
472
|
+
}
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
// Usage
|
|
476
|
+
<ErrorBoundary fallback={<div>Something went wrong</div>}>
|
|
477
|
+
<ScrollSequence source={...} />
|
|
478
|
+
</ErrorBoundary>
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
<br />
|
|
482
|
+
|
|
483
|
+
### 🔄 Multi-Instance & Nested Scroll
|
|
484
|
+
|
|
485
|
+
`react-scroll-media` automatically handles multiple instances on the same page. Each instance:
|
|
486
|
+
|
|
487
|
+
1. Registers with a shared `RAF` loop (singleton) for optimal performance.
|
|
488
|
+
2. Calculates its own progress independently.
|
|
489
|
+
3. Should have a unique `scrollLength` or container setup.
|
|
490
|
+
|
|
491
|
+
<br />
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
## 🏗️ Architecture
|
|
496
|
+
|
|
497
|
+
### 📂 `SequenceSource` Options
|
|
498
|
+
|
|
499
|
+
<br />
|
|
500
|
+
|
|
501
|
+
#### **1. Manual Mode** (Pass array directly)
|
|
502
|
+
|
|
503
|
+
```ts
|
|
504
|
+
{
|
|
505
|
+
type: 'manual',
|
|
506
|
+
frames: ['/img/1.jpg', '/img/2.jpg']
|
|
507
|
+
}
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
<br />
|
|
511
|
+
|
|
512
|
+
#### **2. Pattern Mode** (Generate URLs)
|
|
513
|
+
|
|
514
|
+
```ts
|
|
515
|
+
{
|
|
516
|
+
type: 'pattern',
|
|
517
|
+
url: '/assets/sequence_{index}.jpg', // {index} is replaced
|
|
518
|
+
start: 1, // Start index
|
|
519
|
+
end: 100, // End index
|
|
520
|
+
pad: 4 // Zero padding (e.g. 1 -> 0001)
|
|
521
|
+
}
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
<br />
|
|
525
|
+
|
|
526
|
+
#### **3. Manifest Mode** (Fetch JSON)
|
|
527
|
+
|
|
528
|
+
```ts
|
|
529
|
+
{
|
|
530
|
+
type: 'manifest',
|
|
531
|
+
url: '/sequence.json'
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
// JSON format: { "frames": ["url1", "url2"] } OR pattern config
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
> **💡 Note**: Manifests are cached in memory by URL. To force a refresh, append a query param (e.g. `?v=2`).
|
|
538
|
+
|
|
539
|
+
<br />
|
|
540
|
+
|
|
541
|
+
---
|
|
542
|
+
|
|
543
|
+
## 🎨 How it Works (The "Sticky" Technique)
|
|
544
|
+
|
|
545
|
+
Unlike libraries that use `position: fixed` or JS-based scroll locking (which breaks refreshing and feels unnatural), we use **CSS Sticky Positioning**.
|
|
546
|
+
|
|
547
|
+
<br />
|
|
548
|
+
|
|
549
|
+
<div align="center">
|
|
550
|
+
<img src="https://github.com/iam-saiteja/react-scroll-media/blob/master/demo-213.gif?raw=true" alt="React Scroll Media Technical Demo" width="600" />
|
|
551
|
+
<p><em><strong>Technical Demo:</strong> This visualization shows the direct correlation between the scrollbar position and the rendered frame. The component calculates the exact frame index based on the percentage of the container scrolled, ensuring perfect synchronization without "scroll jacking".</em></p>
|
|
552
|
+
</div>
|
|
553
|
+
|
|
554
|
+
<br />
|
|
555
|
+
|
|
556
|
+
### 🔧 Technical Breakdown
|
|
557
|
+
|
|
558
|
+
1. **Container (`relative`)** — This element has the height you specify (e.g., `300vh`). It occupies space in the document flow.
|
|
559
|
+
|
|
560
|
+
2. **Sticky Wrapper (`sticky`)** — Inside the container, we place a `div` that is `100vh` tall and `sticky` at `top: 0`.
|
|
561
|
+
|
|
562
|
+
3. **Canvas** — The `<canvas>` sits inside the sticky wrapper.
|
|
563
|
+
|
|
564
|
+
4. **Math** — As you scroll the container, the sticky wrapper stays pinned to the viewport. We calculate:
|
|
565
|
+
|
|
566
|
+
```ts
|
|
567
|
+
progress = -containerRect.top / (containerHeight - viewportHeight)
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
This gives a precise **0.0 to 1.0** value tied to the pixel position of the scrollbar. This value is then mapped to the corresponding frame index:
|
|
571
|
+
|
|
572
|
+
```ts
|
|
573
|
+
frameIndex = Math.floor(progress * (totalFrames - 1))
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
This approach ensures:
|
|
577
|
+
* **Zero Jitter**: The canvas position is handled by the browser's compositor thread (CSS Sticky).
|
|
578
|
+
* **Native Feel**: Momentum scrolling works perfectly on touchpads and mobile.
|
|
579
|
+
* **Exact Sync**: The frame updates are synchronized with the scroll position in a `requestAnimationFrame` loop.
|
|
580
|
+
|
|
581
|
+
<br />
|
|
582
|
+
|
|
583
|
+
### 💡 Memory Strategy
|
|
584
|
+
|
|
585
|
+
- **"eager" (Default)** — Best for sequences < 200 frames. Preloads all images into `HTMLImageElement` instances. Instant seeking, smooth playback. High memory usage.
|
|
586
|
+
|
|
587
|
+
- **"lazy"** — Best for long sequences (500+ frames). Only keeps the current frame and its neighbors in memory. Saves RAM, prevents crashes.
|
|
588
|
+
- Buffer size defaults to ±10 frames but can be customized via `lazyBuffer`.
|
|
589
|
+
|
|
590
|
+
<br />
|
|
591
|
+
|
|
592
|
+
---
|
|
593
|
+
|
|
594
|
+
## 🐛 Debugging
|
|
595
|
+
|
|
596
|
+
Enable the debug overlay to inspect your sequence in production:
|
|
597
|
+
|
|
598
|
+
```tsx
|
|
599
|
+
<ScrollSequence
|
|
600
|
+
source={...}
|
|
601
|
+
debug={true}
|
|
602
|
+
/>
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
<br />
|
|
606
|
+
|
|
607
|
+
**Output:**
|
|
608
|
+
|
|
609
|
+
```
|
|
610
|
+
Progress: 0.45
|
|
611
|
+
Frame: 45 / 100
|
|
612
|
+
```
|
|
613
|
+
|
|
614
|
+
This overlay is updated directly via DOM manipulation (bypassing React renders) for **zero overhead**.
|
|
615
|
+
|
|
616
|
+
<br />
|
|
617
|
+
|
|
618
|
+
---
|
|
619
|
+
|
|
620
|
+
<div align="center">
|
|
621
|
+
|
|
622
|
+
## 📄 License
|
|
623
|
+
|
|
624
|
+
**MIT** © 2026 **Thanniru Sai Teja**
|
|
625
|
+
|
|
626
|
+
<br />
|
|
627
|
+
|
|
628
|
+
Made with ❤️ for the React community
|
|
629
|
+
|
|
630
|
+
[⬆ Back to Top](#-react-scroll-media)
|
|
631
|
+
|
|
632
632
|
</div>
|