scroll-utility

4.0.2 verified Fri May 01 auth: no javascript

Simple scroll utility for centering elements and smooth animations. v4.0.2 is the latest stable release (May 2019). Provides a Scroll class to control scroll on any element with customizable easing, duration, and onScroll callbacks. Supports both absolute scrollTo and relative scrollBy with sub-methods for elements, sizes, and scroll sizes. Ships TypeScript types. Differentiators: handles multiple simultaneous animations, detects programmatic vs user scroll, reacts to element position changes, high performance, and works in both Node and browser environments. Designed for precise control over scroll behavior in web applications, with a clean API that avoids common pitfalls of native scroll.

Common errors

error TypeError: scrollManager.scrollTo is not a function ↓

cause Importing the default export instead of named export in ESM environment.

fix

Use import { Scroll } from 'scroll-utility' instead of import Scroll from 'scroll-utility'.

error Scroll is not defined ↓

cause Using the global variable directly without accessing the Scroll property when using CDN.

fix

Use ScrollUtility.Scroll instead of Scroll when loaded via script tag.

error Cannot read property 'scrollTo' of undefined ↓

cause Trying to call scrollTo on a manager that was created without a container, or the container is not scrollable.

fix

Ensure the container element is scrollable (has overflow: auto/scroll and sufficient content). Create manager with explicit container: new Scroll(document.getElementById('container')).

error Property 'element' does not exist on type 'ScrollTo' ↓

cause Using TypeScript with strict mode and missing type definitions for sub-methods.

fix

Update to a version that includes full type definitions. Ensure you are using v4.0.0+ which has complete types.

Warnings

breaking API changed in v4.0.0. The scrollTo method now accepts sub-methods like scrollTo.element, scrollTo.size, and scrollTo.scrollSize instead of separate centerElement, scrollToElement, etc. ↓

fix Update code to use the new API: scrollManager.scrollTo.element('#element') instead of old scrollManager.scrollToElement('#element').

breaking API changed in v3.0.0. Exported classes and methods were refactored. The main export changed from multiple classes to a single Scroll class. ↓

fix Use the new unified Scroll class. Import { Scroll } from 'scroll-utility' and use its scrollTo/scrollBy methods.

gotcha The scroll wrapper (container) must be passed as first argument to the Scroll constructor. If omitted, it defaults to document.scrollingElement or document.documentElement, which may not work as expected in some browsers. ↓

fix Always provide the container element explicitly: new Scroll(document.querySelector('#scrollable')).

gotcha The onScroll callback is called for both user-initiated and programmatic scrolls. Use the isProgrammatic property on the callback argument to distinguish. ↓

fix Check the callback parameter: onScroll: (position, isProgrammatic) => { if (isProgrammatic) return; /* user scroll */ }

deprecated Multiple scrolling animations queued simultaneously may cause glitches. v4.0.2 still has some known issues with detection of external scroll changes. ↓

fix Monitor for future releases that might fix glitchy behavior. Consider using a single animation at a time or implementing a queue.

Install

npm install scroll-utility

yarn add scroll-utility

pnpm add scroll-utility

Imports

Scroll
wrong
```
import Scroll from 'scroll-utility'
```
correct
```
import { Scroll } from 'scroll-utility'
```
Named export, not default. Also available globally as ScrollUtility.Scroll when using CDN.
ScrollManager
wrong
```
const { ScrollManager } = require('scroll-utility')
```
correct
```
import { ScrollManager } from 'scroll-utility'
```
ScrollManager is an alias for Scroll. Both named exports are identical. Available in CJS via destructuring.
ScrollUtility (global)
wrong
```
const Scroll = window.ScrollUtility;
```
correct
```
const scrollUtility = window.ScrollUtility; const Scroll = scrollUtility.Scroll;
```
When using CDN script tag, the library is exported as a global variable ScrollUtility, not directly as Scroll.

Quickstart

Demonstrates basic scroll operations: scrolling to position, centering an element, relative scrolling, and creating a manager for a specific container.

import { Scroll } from 'scroll-utility';

const scrollManager = new Scroll();

// Scroll to a specific pixel position
scrollManager.scrollTo(500);

// Smooth scroll to an element and center it
scrollManager.scrollTo.element('#my-element', 0.5, 1000);

// Scroll relative
scrollManager.scrollBy(200);

// Get current scroll position
const pos = scrollManager.scrollPosition();

// Create a manager for a specific scrollable container
const container = document.querySelector('.scrollable');
const containerManager = new Scroll(container);
containerManager.scrollTo.scrollSize(1); // scroll to bottom