Registry / web-framework / scroll-utility

scroll-utility

library4.0.2jsnpmunverified

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.

web-framework

npm install scroll-utility

github ↗package ↗

INSTALL

IMPORT

SIG · SCROLL-UTILITY

scroll-utility

web-frameworkjavascriptv4.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Scroll

✓ import { Scroll } from 'scroll-utility'

✗ import Scroll from 'scroll-utility'

Named export, not default. Also available globally as ScrollUtility.Scroll when using CDN.

ScrollManager

✓ import { ScrollManager } from 'scroll-utility'

✗ const { ScrollManager } = require('scroll-utility')

ScrollManager is an alias for Scroll. Both named exports are identical. Available in CJS via destructuring.

ScrollUtility (global)

✓ const scrollUtility = window.ScrollUtility; const Scroll = scrollUtility.Scroll;

✗ const Scroll = window.ScrollUtility;

When using CDN script tag, the library is exported as a global variable ScrollUtility, not directly as Scroll.

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

Debug

Known issues

breakingAPI 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').

affects: >=4.0.0

breakingAPI 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.

affects: >=3.0.0

gotchaThe 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')).

affects: >=2.0.0

gotchaThe 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 */ }

affects: >=2.0.0

deprecatedMultiple 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.

affects: <=4.0.2

Errors

Common errors & fixes

TypeError: scrollManager.scrollTo is not a function

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'.

Scroll is not defined

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.

Cannot read property 'scrollTo' of undefined

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')).

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

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.

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/LeDDGroup/scroll-utility ↗

packagehttps://www.npmjs.com/package/scroll-utility ↗