Controller API and events
Every method, event and state field of the scroll video API, for React, the element and the core.
The same API is reachable three ways:
| Where | How | Available |
|---|---|---|
| React | useScrollVideo().api | The methods under Methods |
<vid-scroll> | element.api | Methods plus core-only |
vidscroll/core | the return value of createScrollVideo | Methods plus core-only |
The api is null until the component has mounted (React) or the element has
started. Until the video is ready, methods are safe to call and do nothing,
and getState returns zeros.
Methods
on(event, handler) / off(event, handler)
Subscribe to and unsubscribe from events. Listeners stay attached for the life of the component, including when the video reloads.
getState()
Returns the state right now.
isReady()
true once the video is loaded and following the scroll.
scrollToTime(seconds, options?)
Scrolls the page to the position where the video shows seconds. options
is { behavior?: "smooth" | "instant" | "auto" }, smooth by default. Does
nothing until the video’s duration is known, and nothing in ScrollFrames.
scrollToProgress(progress, options?)
Scrolls the page to a progress between 0 and 1 (clamped). Same options.
getSectionProgress(id)
The section’s progress from 0 to 1, the same value as its --progress
variable. 0 for unknown ids.
addSection(range) / removeSection(id)
Adds or removes a tracked range. range is
{ id, start?, end?, fromTime?, toTime?, fromFrame?, toFrame? }. Adding an id
that already exists throws. React’s <Section> and <vid-scroll-section> call
these for you.
Core only
Available on element.api and on the controller from createScrollVideo.
| Method | What it does |
|---|---|
update(options) | Changes the options you pass; the others keep their values. |
setOptions(options) | Replaces all options; omitted ones return to their defaults. |
getLoader() | The current loader state, or null. |
destroy() | Stops everything, removes the video and all listeners. |
State
Returned by getState() and passed to update, ready and resize handlers.
| Field | Type | Meaning |
|---|---|---|
linearProgress | number | Smoothed scroll progress through the block, 0 to 1 |
time | number | Video time in seconds (frame ÷ fps in ScrollFrames) |
frameIndex | number | Current frame |
totalFrames | number | Frame count |
duration | number | Video length in seconds (0 in ScrollFrames) |
activeSections | string[] | Ids of the active sections |
useScrollVideoState() returns a simplified version:
{ ready, progress, time, frame, activeSections }.
Events
| Event | Payload | Fires |
|---|---|---|
update | state | Every frame while the video moves, and once when the scroll mapping is rebuilt |
ready | state | The video is ready; again after the scroll mapping is rebuilt |
sectionEnter | { id, state } | A section becomes active |
sectionExit | { id, state } | A section becomes inactive |
warmup | { value } | Progress of the pass over the timeline while loading, 0 to 1 |
resize | state | The window is resized |
loader | loader state or null | The loading state changes (core and element only) |
The scroll mapping is rebuilt when length, fps or smooth scrolling on/off
changes, or when the video falls back to another copy. Active sections get a
sectionExit first, then sectionEnter again from the new mapping.
The element also fires DOM events: see
<vid-scroll> events.
Loader state
| Field | Type | Meaning |
|---|---|---|
phase | “download” | “optimize” | “preparing” | “error” | What’s happening |
progress | number | 0 to 1 within the phase |
background | boolean | true while the original is already scrollable during a re-encode |
error | Error | Only in the error phase |
Related
- Hooks: using the api from React.
- vidscroll/core: creating a controller.