Skip to main content

ScrollProgress

Tracks scroll progress of a section relative to the viewport or a custom scroll root.
Useful for parallax, scrubbed animations, and enter/leave effects.

Initialization​

import { ScrollProgress, vevet } from 'vevet';

const section = document.getElementById('section');

const progress = new ScrollProgress({
  section,
  onUpdate: () => {
    const { y } = progress.moveProgress;
    section.style.setProperty('--p', String(y));
  },
});

Destroying the instance removes the scroll listener and disconnects the IntersectionObserver:

progress.destroy();

Props​

Static Props​

Static properties are set during initialization and cannot be modified later.

section​

  • Type: Element
  • The element whose scroll progress is tracked.

root​

  • Type: Element | null
  • Default: null
  • The root element used as a reference for scroll progress calculation.
  • Usually the scroll container.
  • If null, the viewport is used as the reference.

optimized​

  • Type: boolean
  • Default: true
  • If true, progress calculations occur only while the section is within the viewport or root element.
  • Improves performance by avoiding unnecessary calculations.

useSvh​

  • Type: boolean
  • Default: false
  • If true, scroll progress is calculated based on the small viewport height (svh CSS unit) instead of the current viewport height (vh CSS unit).

Accessors​

note

All Module accessors are available in this class.

inProgress​

Type: { x: number; y: number }

Calculates the progress of the section entering the root element.

isVisible​

Type: boolean

Indicates whether the section is currently visible within the viewport or root element.

moveProgress​

Type: { x: number; y: number }

Calculates the progress of the section's movement within the root element.

outProgress​

Type: { x: number; y: number }

Calculates the progress of the section leaving the root element.

progress​

Type: { x: number; y: number }

Calculates the global scroll progress of the section relative to the root element.

rootBounds​

Type: { height: number; left: number; top: number; width: number }

The bounds of the root element used for scroll calculations.

section​

Type: Element

Returns the section element being tracked for scroll progress.

sectionBounds​

Type: { height: number; left: number; top: number; width: number }

The bounds of the section element relative to the root element.

Methods​

note

All Module methods are available in this class.

getProgress​

Calculates the section scroll progress relative to the root element.

The function takes the top or left corner of the section as the reference point.

Parameters

  • topThreshold: number Top threshold of the section position.

  • rightThreshold: number Right threshold of the section position.

  • bottomThreshold: number Bottom threshold of the section position.

  • leftThreshold: number Left threshold of the section position.

const progress = instance.getProgress(0, vevet.width, vevet.height / 2, 0);

// `progress.y` is `0` when the top corner of the section is at the beginning of the viewport or root element
// `progress.y` is `1` when the top corner of the section is at the center of the viewport or root element

update​

Updates the section and root bounds, and emits an update callback.

instance.update();

// Force update even when the section is not visible (optimized mode)
instance.update(true);

destroy​

Releases the scroll listener and disconnects the IntersectionObserver.

instance.destroy();

Callbacks​

note

All Module callbacks are available in this class.

update​

Triggered on each scroll progress update.

const destruct = instance.on('update', () => console.log('update'));

// Cancel the callback
destruct();