stroll.js

A tiny library without dependencies for smooth scrolling in modern browsers. Think of Mr. Toast!

Installation

NPM

npm install stroll.js --save

Script

Just include the dist/scroll.min.js but refer to the polyfill section below. As the dist folder is not part of the repository you still need to install the package via npm.

Usage

import stroll from "stroll.js";

stroll(".target");

stroll returns native Promises. It resolves to an object once scrolling is complete. The object contains a single property named wasCancelled that indicates if scrolling was completed (in case stroll was called again before it finished it’s false).

stroll’s first argument can be a number (absolute position in viewport on primary scroll axis), a selector string, an object with an x and/or y key or something that has a getBoundingClientRect function. You can also pass null, if you want to scroll from the current position.

Whenever the term primary scroll axis is used it refers to the axis of an element that has the largest scroll width. On window this most likely always is the y axis. For elements it depends. A carousel will probably use the x axis.

stroll’s second argument can be an object, with one or more of the following properties:

duration (number|function, 500)

Time in milliseconds or a function that returns a duration for a given distance on x and y axis.

offset (number|object, 0)

Is added to the final scroll position. Accepts an object with x and y key, or a number that is used for the primary scroll axis.

focus (bool, true)

Should the element you scroll to be focused once scrolling is done? this keeps keyboard navigation intact.

easing (function, easeInOutQuad from Robert Penner)

Timing function that is used to animate the scroll position.

ignoreUserScroll (bool, false)

Whether or not programmatic scrolling should be aborted when a user has scrolled. This works by checking if the last set scroll position equals the current position.

allowInvalidPositions (bool, false)

Whether or not positions outside of the document are allowed during strolling or should trigger an early exit.

Examples

Relative Scrolling

Scroll 100px from the current position.

stroll(null, { offset: 100 })
// or
stroll.relative(100)

Changing defaults

Change default duration to 2 seconds.

stroll.DEFAULTS.duration = 2 * 1000

ALL the settings

Scroll to target link anchor - 70px with easeInOutElastic easing for a duration of 10 times the distances to the element, don’t focus and allow invalid positions during animation.

stroll(target.getAttribute("href"), {
    offset: -70,
    duration: (distance) => 10 * (distance.x + distance.y),
    focus: false,
    allowInvalidPositions: true,
    easing: (t, b, c, d) => {
        var s=1.70158;var p=0;var a=c;
        if (t==0) return b;  if ((t/=d/2)==2) return b+c;  if (!p) p=d*(.3*1.5);
        if (a < Math.abs(c)) { a=c; var s=p/4; }
        else var s = p/(2*Math.PI) * Math.asin (c/a);
        if (t < 1) return -.5*(a*Math.pow(2,10*(t-=1)) * Math.sin( (t*d-s)*(2*Math.PI)/p )) + b;
        return a*Math.pow(2,-10*(t-=1)) * Math.sin( (t*d-s)*(2*Math.PI)/p )*.5 + c + b;
    }
});

Promise API

Stroll to .target, wait 2 seconds, scroll +500px from current position, wait 1 second, scroll to beginning of the document.

function wait(time) {
    return new Promise((resolve, reject) => {
        setTimeout(resolve, time);    
    });
}

stroll(".target")
    .then(() => wait(2 * 1000))
    .then(() => stroll.relative(500))
    .then(() => wait(1 * 1000))
    .then(() => stroll(0));

Scroll elements instead of window

stroll.js is able to scroll the window as well as elements. If you want to stroll an element you first must create a stroll instance for this element.

const element = document.querySelector(".some-element");
const elementStroller = stroll.factory(element);
elementStroller.relative(500);

The elementStroller instance will have the same API as the default stroll instance (it misses the factory function though).

Browser Compatibility

stroll.js is build for modern Browsers. It uses the Object.assign, requestAnimationFrame and Promise APIs. You may want to polyfill these. requestAnimationFrame is widespread nowadays, but Object.assign and Promises are quite new additions and part of ES-2015. Polyfills that should work for you:

• requestAnimationframe: raf
• Object.assign: object-assign-shim
• Promise: es6-promise

Without polyfills you should be fine in Edge (12+), Safari 9 and and all current versions of Firefox and Chromium/Chrome.

Shout-out

... goes to jump.js for inspiring me to create my own implementation. They’ve worked on v1.0.0, when I created this, and I wasn’t happy with 0.4.0 :).