scroll-animator

Smart, lightweight functions to animate browser scroll.

• Scroll the page or a specific element.
• Scroll vertically and horizontally.
• Scroll to a target element or an arbitrary position, with an optional offset.
• Scroll animations can be interrupted by the user or other scripts (no “fighting” animations).
• Scroll animations adapt to a moving target; handy when loading affects layout.
• Intuitive easeInOutCubic animation timing; a soft acceleration and deceleration.
• < 1 kB bundle size, tested.
• SSR friendly.

Installation

For Node.js, to install scroll-animator with npm, run:

npm install scroll-animator

For Deno and browsers, an example import map:

{
  "imports": {
    "scroll-animator/": "https://unpkg.com/scroll-animator@4.0.0/"
  }
}

Requirements

Supported runtime environments:

• Node.js versions ^14.17.0 || ^16.0.0 || >= 18.0.0.
• Deno.
• Browsers matching the Browserslist query > 0.5%, not OperaMini all, not dead.

Consider polyfilling:

• document.scrollingElement
• window.requestAnimationFrame

Non Deno projects must configure TypeScript to use types from the ECMAScript modules that have a // @ts-check comment:

• compilerOptions.allowJs should be true.
• compilerOptions.maxNodeModuleJsDepth should be reasonably large, e.g. 10.
• compilerOptions.module should be "node16" or "nodenext".

Exports

The npm package scroll-animator features optimal JavaScript module design. It doesn’t have a main index module, so use deep imports from the ECMAScript modules that are exported via the package.json field exports:

• animateScroll.mjs
• scrollToElement.mjs