scroll-to-position
TypeScript icon, indicating that this package has built-in type declarations

1.7.19 • Public • Published

scroll-to-position

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

Demo

GitHub release Build Status Codacy Badge

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.

Readme

Keywords

Package Sidebar

Install

npm i scroll-to-position

Weekly Downloads

21

Version

1.7.19

License

MIT

Unpacked Size

355 kB

Total Files

21

Last publish

Collaborators

  • bameyrick