scroll-animator

4.0.0 • Public • Published

scroll-animator

npm version CI status

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.

Setup

To install with npm, run:

npm install scroll-animator

Support

  • Node.js: ^12.20 || >= 14.13
  • Browsers: > 0.5%, not OperaMini all, not IE > 0, not dead

Consider polyfilling:

API

function animateScroll

Smoothly scrolls an element to a target position within the element. Scroll interference caused by the user or another script interrupts the animation.

Parameter Type Description
options object Options.
options.container HTMLElement? = document.scrollingElement Container element to scroll.
options.targetX number? Target X position within the container, defaulting to the current position.
options.targetY number? Target Y position within the container, defaulting to the current position.
options.offsetX number? = 0 Target X position offset.
options.offsetY number? = 0 Target Y position offset.
options.duration number? = 500 Total scroll animation duration in milliseconds.
options.onInterrupt Function? Callback to run if the scroll animation is interrupted.
options.onArrive Function? Callback to run after scrolling to the target.

Examples

Ways to import.

import { animateScroll } from 'scroll-animator';
import animateScroll from 'scroll-animator/public/animateScroll.js';

Ways to require.

const { animateScroll } = require('scroll-animator');
const animateScroll = require('scroll-animator/public/animateScroll.js');

Horizontally scroll an element to a certain position.

animateScroll({
  container: document.getElementById('panner'),
  targetX: 400,
});

function scrollToElement

Scrolls a container to a target element, using animateScroll. The animation adapts to a moving target; handy when loading affects layout.

Parameter Type Description
options object Options.
options.container HTMLElement? = document.scrollingElement Container element to scroll.
options.target HTMLElement Target element to scroll to.
options.offsetX number? = 0 Target X position offset.
options.offsetY number? = 0 Target Y position offset.
options.duration number? = 500 Total scroll animation duration in milliseconds.
options.onInterrupt Function? Callback to run if the scroll animation is interrupted.
options.onArrive Function? Callback to run after scrolling to the target.

Examples

Ways to import.

import { scrollToElement } from 'scroll-animator';
import scrollToElement from 'scroll-animator/public/scrollToElement.js';

Ways to require.

const { scrollToElement } = require('scroll-animator');
const scrollToElement = require('scroll-animator/public/scrollToElement.js');

Scroll the page to an element.

scrollToElement({
  target: document.getElementById('contact-us'),
});

Package Sidebar

Install

npm i scroll-animator

Weekly Downloads

12

Version

4.0.0

License

MIT

Unpacked Size

15.1 kB

Total Files

9

Last publish

Collaborators

  • jaydenseric