{"id":26369,"library":"scroll-utility","title":"scroll-utility","description":"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.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/LeDDGroup/scroll-utility","tags":["javascript","scroll","smooth","simple","center","scrolling","centering","typescript"],"install":[{"cmd":"npm install scroll-utility","lang":"bash","label":"npm"},{"cmd":"yarn add scroll-utility","lang":"bash","label":"yarn"},{"cmd":"pnpm add scroll-utility","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Named export, not default. Also available globally as ScrollUtility.Scroll when using CDN.","wrong":"import Scroll from 'scroll-utility'","symbol":"Scroll","correct":"import { Scroll } from 'scroll-utility'"},{"note":"ScrollManager is an alias for Scroll. Both named exports are identical. Available in CJS via destructuring.","wrong":"const { ScrollManager } = require('scroll-utility')","symbol":"ScrollManager","correct":"import { ScrollManager } from 'scroll-utility'"},{"note":"When using CDN script tag, the library is exported as a global variable ScrollUtility, not directly as Scroll.","wrong":"const Scroll = window.ScrollUtility;","symbol":"ScrollUtility (global)","correct":"const scrollUtility = window.ScrollUtility; const Scroll = scrollUtility.Scroll;"}],"quickstart":{"code":"import { Scroll } from 'scroll-utility';\n\nconst scrollManager = new Scroll();\n\n// Scroll to a specific pixel position\nscrollManager.scrollTo(500);\n\n// Smooth scroll to an element and center it\nscrollManager.scrollTo.element('#my-element', 0.5, 1000);\n\n// Scroll relative\nscrollManager.scrollBy(200);\n\n// Get current scroll position\nconst pos = scrollManager.scrollPosition();\n\n// Create a manager for a specific scrollable container\nconst container = document.querySelector('.scrollable');\nconst containerManager = new Scroll(container);\ncontainerManager.scrollTo.scrollSize(1); // scroll to bottom","lang":"typescript","description":"Demonstrates basic scroll operations: scrolling to position, centering an element, relative scrolling, and creating a manager for a specific container."},"warnings":[{"fix":"Update code to use the new API: scrollManager.scrollTo.element('#element') instead of old scrollManager.scrollToElement('#element').","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use the new unified Scroll class. Import { Scroll } from 'scroll-utility' and use its scrollTo/scrollBy methods.","message":"API changed in v3.0.0. Exported classes and methods were refactored. The main export changed from multiple classes to a single Scroll class.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always provide the container element explicitly: new Scroll(document.querySelector('#scrollable')).","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Check the callback parameter: onScroll: (position, isProgrammatic) => { if (isProgrammatic) return; /* user scroll */ }","message":"The onScroll callback is called for both user-initiated and programmatic scrolls. Use the isProgrammatic property on the callback argument to distinguish.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Monitor for future releases that might fix glitchy behavior. Consider using a single animation at a time or implementing a queue.","message":"Multiple scrolling animations queued simultaneously may cause glitches. v4.0.2 still has some known issues with detection of external scroll changes.","severity":"deprecated","affected_versions":"<=4.0.2"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use import { Scroll } from 'scroll-utility' instead of import Scroll from 'scroll-utility'.","cause":"Importing the default export instead of named export in ESM environment.","error":"TypeError: scrollManager.scrollTo is not a function"},{"fix":"Use ScrollUtility.Scroll instead of Scroll when loaded via script tag.","cause":"Using the global variable directly without accessing the Scroll property when using CDN.","error":"Scroll is not defined"},{"fix":"Ensure the container element is scrollable (has overflow: auto/scroll and sufficient content). Create manager with explicit container: new Scroll(document.getElementById('container')).","cause":"Trying to call scrollTo on a manager that was created without a container, or the container is not scrollable.","error":"Cannot read property 'scrollTo' of undefined"},{"fix":"Update to a version that includes full type definitions. Ensure you are using v4.0.0+ which has complete types.","cause":"Using TypeScript with strict mode and missing type definitions for sub-methods.","error":"Property 'element' does not exist on type 'ScrollTo'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}