ScrollBooster

You can install ScrollBooster using npm, yarn, or by including a <script> tag directly in your HTML.

npm i scrollbooster

yarn add scrollbooster

<script src="https://unpkg.com/scrollbooster@2/dist/scrollbooster.min.js"></script>

To initialize ScrollBooster, create a new instance of the ScrollBooster class and provide a configuration object. At minimum, you must specify the viewport element. It is recommended to set scrollMode to 'transform' for smooth CSS-based scrolling.

import ScrollBooster from 'scrollbooster';

new ScrollBooster({
    viewport: document.querySelector('.viewport'),
    scrollMode: 'transform'
});

The ScrollBooster instance provides several methods to control the scrolling state and instance lifecycle:

• setPosition({ x, y }): Sets a new scroll position in the viewport.
• scrollTo({ x, y }): Smoothly scrolls to a position in the viewport.
• updateMetrics(): Forces recalculation of element metrics (use when content size changes dynamically).
• updateOptions(options): Updates configuration using any property from the Options object.
• getState(): Returns the current scroll state (same format as onUpdate).
• destroy(): Removes all event listeners and cleans up the instance.

Use the scrollTo method to animate the scroll position to a specific coordinate. This uses an internal force-based animation loop for a smooth effect.

// Scroll to x: 100, y: 200
sb.scrollTo({ x: 100, y: 200 });

Call getState() to retrieve the current interaction and position metrics. The returned object contains:

• isMoving: boolean - True if the content is currently scrolling or being dragged.
• isDragging: boolean - True if a pointer drag is in progress.
• position: { x: number, y: number } - The current scroll position (relative to the top-left).
• dragOffset: { x: number, y: number } - The current drag offset.
• dragAngle: number - The angle of the current drag (up: 180, left: -90, right: 90, down: 0).
• borderCollision: { left: boolean, right: boolean, top: boolean, bottom: boolean } - Whether the content is colliding with the viewport edges.

const state = sb.getState();
console.log(state.position);
console.log(state.isMoving);

To prevent memory leaks and remove all attached event listeners from the viewport and window, call the destroy() method when the component or page is unmounted.

sb.destroy();

The ScrollBooster instance provides the following methods to control scrolling and state:

• updateOptions(options): Merges new options into the existing configuration and triggers an update.
• scrollTo(position): Smoothly scrolls to the specified { x, y } coordinates.
• setPosition(position): Manually sets the scroll position to { x, y } without velocity.
• getState(): Returns the current state of the instance.
• destroy(): Removes all DOM event listeners and cleans up the instance.