scroll-to-position

Animate scroll to either an x, y, or x and y position in any scrollable viewport with customisable easing.

Install

You can install via npm or yarn.

npm

npm install --save scroll-to-position

yarn

yarn add scroll-to-position

Usage

Importing

You can import using ES6 imports.

import { ScrollTo } from 'scroll-to-position';

Arguments

ScrollTo accepts two arguments:

target: either a position ([positionX, positionY]) or a HTML Element (e.g. a reference to a div).

options (optional): an object of configuration options - see the options section below.

Examples

Position

ScrollTo([0, 100]);

Element

const myElement = document.querySelector('.MyElement');
ScrollTo(myElement);

Note: if you're using TypeScript you will most likely need to cast your element to a HTMLElement, as document.querySelector returns a Element type.

Callback

Calling ScrollTo returns a Promise, so it is possible to run your own code after scrolling has completed.

ScrollTo([0, 100]).then(() => console.log('Scrolling completed'));

If cancelOnUserScroll is enabled and the user interrupts scrolling, then the promise rejects and can be caught using Promise.prototype.catch

ScrollTo([0, 100])
  .then(() => console.log('Scrolling completed'))
  .catch(() => console.log('User interrupted scrolling'));

Options

When calling ScrollTo you can provide an options object, with values to override the defaults.

Option Parameters

Parameter	Type	Description	Default
scrollContainer	HTMLElement or Window	The area to scroll. e.g. window or a div with overflow auto	window
offset	Position ([number, number])	If your target is a HTMLElement you may want to provide an offset to prevent scrolling right to the edge of the element	[0,0]
duration	DurationRange ([number, number]) or Duration (number)	Either a DurationRange ([minDuration, maxDuration]) or a set duration (all values in milliseconds). If you provide a range the scroll distance (providing it's no less than the minDuration and no more than the maxDuration will be used as the duration)	[200, 5000]
easing	string	The easing function the animation will use. The easing's available can be seen in my js-easing-functions repo (https://github.com/bameyrick/js-easing-functions)	https://github.com/bameyrick/js-easing-functions
cancelOnUserScroll	boolean	Whether the scroll animation should stop when the user scrolls	true
animate	boolean	Whether ScrollTo should animate to the target, or jump straight there with no animation	true
autoDurationMultiplier	number	If duration is to picked automatically (between DurationRange), multiply the distance to travel by this value to get the duration	2
onlyScrollIfNotInView	boolean	Only scroll if the target is not within the viewport of the scrollable area. If the provided target is a DOM element then it will check to see if the element is fully within the scroll area.	false

Example of providing options

ScrollTo([0, 100], {
  duration: [300, 1000],
  easing: 'easeInOutSine',
});

Using the easing enum in TypeScript

import { ScrollTo, Easing } from 'scroll-to-position';

ScrollTo([0, 100], {
  duration: [300, 1000],
  easing: Easing.easeInQuad,
});

Extras

An autoScroll boolean is added to the window which you can use in your scroll event listeners to check if the window is being autoScrolled by this package.

bameyrick/scroll-to-position