Plain HTML · vidscroll

Add a scroll video to any page with the <vid-scroll> element, no framework needed.

<vid-scroll> is a custom element, so it works anywhere you can add HTML and a script tag: plain pages, site builders and template engines. It runs the same loading, re-encoding and scrubbing as the React component.

Set it up

Load the element. From a CDN, with no build step, add this to your page’s <head>:
index.html
```
<script type="module" src="https://cdn.jsdelivr.net/npm/vidscroll@0.3/dist/cdn/vidscroll-element.js"></script>
```
Or, if your site has a bundler, install it and import it once:
```
npm install vidscroll
```
```
pnpm add vidscroll
```
```
yarn add vidscroll
```
```
bun add vidscroll
```
main.js
```
import "vidscroll/element";
```

Add the element where the video should appear.

index.html

<vid-scroll src="/videos/hero.mp4" length="400vh">
  <vid-scroll-section start="0" end="0.3">
    <h2>Doors close</h2>
  </vid-scroll-section>
  <vid-scroll-section start="0.55" end="0.9">
    <h2>Open water</h2>
  </vid-scroll-section>
</vid-scroll>

The CDN version is pinned to 0.3, so a future release can’t change your page unexpectedly. The pinning caveat from the React page applies here too: a parent with overflow: hidden stops the video from pinning.

Scroll inside the preview

index.html

<script type="module" src="https://cdn.jsdelivr.net/npm/vidscroll@0.3/dist/cdn/vidscroll-element.js"></script>

<vid-scroll src="/train.mp4" length="400vh">
  <vid-scroll-section id="doors" start="0" end="0.3">
    <h2>Doors close</h2>
  </vid-scroll-section>
  <vid-scroll-section id="water" start="0.55" end="0.9">
    <h2>Open water</h2>
  </vid-scroll-section>
</vid-scroll>

Everything inside <vid-scroll> stays ordinary page content, shown over the pinned video, so your CSS styles it as usual. Sections get a data-active attribute while active and a --progress variable from 0 to 1 across their range.

Attributes

The element takes the same options as the React component, written in kebab-case:

Attribute	Example	Meaning
`src`	`"/videos/hero.mp4"`	Video file URL
`length`	`"400vh"`	Scrolling that covers the whole video
`easing`	`"inOutSine"`	Curve from scroll to video time
`fit`	`"contain"`	`cover` (default) or `contain`
`smooth-scroll`	(no value)	Eased mouse-wheel scrolling
`poster`	`"/poster.jpg"`	Image while loading, `"none"` for none
`optimize`	`"false"` or `"wait"`	Skip the re-encode, or wait for it
`loader`	`"none"`	Hide the loading overlay

Sections take start and end (0 to 1), from-time and to-time (seconds), or from-frame and to-frame.

From JavaScript

main.js

const video = document.querySelector("vid-scroll");

video.scrollToTime(12);

video.addEventListener("vidscroll-enter", (event) => {
  console.log("entered", event.detail.id);
});

The element fires vidscroll-load, vidscroll-ready, vidscroll-loader and vidscroll-error; sections fire vidscroll-enter and vidscroll-exit. All of them bubble.

Next steps

How it works: loading, keyframes and re-encoding.
ScrollVideo: the options explained in depth (the element takes the same ones).