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.