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.

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:

• document.scrollingElement
• window.requestAnimationFrame

API

• function animateScroll
• function scrollToElement

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'),
});