ScrollyVideo

Components for scroll-based (or other externally controlled) playback.

VideoScrollingReactVueSvelte
dkaoster/scrolly-videoscrollyvideo.js.org/scrolly-video

README

ScrollyVideo.js


A component for scroll-based (or other externally controlled) playback. See [/demos](https://github.com/dkaoster/scrolly-video/tree/main/demos) for full example usages.

🚀 Web


Add html container to your page:

  1. ```html
  2. <div id="scrolly-video"></div>
  3. ```

Require javascript in your page and create the object (before ``):

  1. ```html
  2. <script src="https://cdn.jsdelivr.net/npm/scrolly-video@latest/dist/scrolly-video.js"></script>
  3. <script type="text/javascript">
  4.   new ScrollyVideo({
  5.     scrollyVideoContainer: "scrolly-video",
  6.     src: "https://scrollyvideo.js.org/goldengate.mp4"
  7.   });
  8. </script>
  9. ```

You can replace @latest with specific version, example @0.0.2.

🔵 React


Install npm module with npm install scrolly-video --save:
Import component in your application:

  1. ```javascript
  2. import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.jsx';
  3. ```

Add the component where you need it:

  1. ```html
  2. <ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
  3. ```

🟠 Svelte


Install npm module with npm install scrolly-video --save:
Import component in your application:

  1. ```javascript
  2. import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.svelte';
  3. ```

Add the ScrollyVideo component to your application:

  1. ```html
  2. <ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
  3. ```

🟢 Vue


Install npm module with npm install scrolly-video --save:
Import module in your src/App.vue and config:

  1. ```javascript
  2. import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.vue';
  3. ```

Add html code to your html component:

  1. ```html
  2. <ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
  3. ```

🧰 Options / Attributes


| Parameter | Description | Values | Default |
| :---| :--- | :--- | :--- |
| src | The URL of the video (required) | URL | |
| scrollyVideoContainer | The DOM element of the container, only used for plain js | String / Element | |
| transitionSpeed | Sets the maximum playbackRate for this video | Number | 8 |
| frameThreshold | When to stop the video animation, in seconds | Number | 0.1 |
| cover | Forces the video to cover in it's container | Boolean | true |
| sticky | Whether the video should have position: sticky | Boolean | true |
| full | Whether the video should take up the entire viewport | Boolean | true |
| trackScroll | Whether this object should automatically respond to scroll | Boolean | true |
| useWebCodecs | Whether the library should use the webcodecs method, see below | Boolean | true |
| videoPercentage | Manually specify the position of the video between 0..1, only used for react, vue, and svelte components | Number | |
| debug | Whether to log debug information | Boolean | false |

Additionally, to set currentTime manually:

setCurrentTimePercent (setPercentage | Number): A number between 0 and 1 that specifies the percentage position of the video.

Technical Details and Cross Browser Differences

To make this library perform optimally in all browsers, three different approaches are taken to animating the video.

Method 1: WebCodecs and Canvas


Using the new WebCodecs API we are able to get all frames in the video and have them ready to draw to a canvas. This method is the most performant, but has two drawbacks: first, depending on the device and the size of the video, using the WebCodecs API will take some time to process all the frames, so the animation will not be available immediately upon page load. Secondly, the WebCoedecs API is currently only available on Chrome, and the WebCodecs polyfill does not work for this application.

If WebCodecs is not supported by the browser or has not finished processing all frames, it falls back to method 2:

Method 2: HTML5 Video and playbackRate


This method simply embeds the video with an HTML `