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:

``sh
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

$3

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

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

_Ways to require._

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

_Horizontally scroll an element to a certain position._

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

---

$3

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

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

_Ways to require._

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

_Scroll the page to an element._

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