SmoothScroller

Description

SmoothScroller is a JavaScript module that provides easy-to-use and customizable smooth scrolling functionality for your website. You can easily change scroll duration and easing, as well as listen for custom events so that your own code can react appropriately to scroll starts and stops. If you would like to see it in action, check out the demos at damianmgarcia.com.

Also, check out MomentumScroller. It is a JavaScript module that provides easy-to-use and customizable momentum scrolling functionality for your website's mouse-users and is designed to work well with SmoothScroller.

Features

Performs smooth scrolls with custom duration and easing
Dispatches custom events and returns a promise so your code can easily react

Installation

Import SmoothScroller:

import { SmoothScroller } from "https://damianmgarcia.com/scripts/modules/smooth-scroller.js";

Usage (Basic)

Example of smooth scrolling the <body> element to a scrollTop of 1000, with a duration of 1.5 seconds, and an easing of "ease-out":

SmoothScroller.scroll({
  scrollContainer: document.querySelector("body"),
  y: 1000,
  duration: 1500,
  easing: "ease-out",
});

Usage (Advanced)

Below is a list of all static and instance methods.

Method names are bolded and are followed by a description of the method's function.

If a method has parameters, they are listed in order below the method description. Parameter names are italicized, and if they have a default value, they are also italicized, followed by a description of the parameter's function. Some parameters are options objects.

Static Methods:

scroll — Initiates a smooth scroll if the scrollContainer has scrollable area. It returns a Promise.
- Options Object:
  - scrollContainer — The Element to be scrolled.
  - x — scrollContainer.scrollLeft — A Number indicating the desired horizontal position to scroll to.
  - y — scrollContainer.scrollTop — A Number indicating the desired vertical position to scroll to.
  - duration — 600 — A Number indicating the desired scroll duration in milliseconds.
  - easing — "ease" — A String or Array representing a Cubic-Bezier easing function. Valid String values include: "ease", "ease-in", "ease-in-out", "ease-out", and "linear". Valid Arrays must be in the form of [P₁x, P₁y, P₂x, P₂y], and each P value must be a Number. P₁x and P₂x must be within the range [0, 1].
  - stopScrollOnPointerDown — true — A Boolean that determines how ongoing smooth scrolls react to pointerdown events on the scrollContainer. If set to true, ongoing smooth scrolls will stop if a pointerdown event occurs on the scrollContainer. If set to false, ongoing smooth scrolls will not stop if a pointerdown event occurs on the scrollContainer.
getScroller — Gets and returns a SmoothScroller instance if found, which gives you access to its methods; Otherwise, returns undefined.
- scrollContainer — The Element that has SmoothScroller functionality.
getAllScrollers — Gets and returns an Array of all SmoothScroller instances. The forEach method may then be called to perform batch operations.

Instance Methods:

getScrollerData — Gets and returns an Object containing the following instance properties: scrollContainer, scrolling.

Events

Below is a list of all CustomEvents dispatched by SmoothScroller. You can listen for them with the addEventListener method.

Event names are bolded and are followed by a description of the trigger that leads to their dispatch.

If an event includes custom properties in the CustomEvent details object, they are listed below the event description. Custom property names are italicized and are followed by a description.

Instance Events:

smoothScrollerStart — Dispatches at the beginning of a smooth scroll
- scrollContainer — The SmoothScroller instance's scroll container
- startPoint — The starting coordinates
- endPoint — The ending coordinates
- distance — The distance scrolled
- duration — The calculated duration of the scroll
- elapsedTime — The elapsed time of the scroll, which will be less than the calculated duration if the scroll was interrupted
- interruptedBy — The cause of a scroll's interruption if it was interrupted; Otherwise, null
smoothScrollerScroll — Dispatches continuously while smooth scrolling
- Same as smoothScrollerStart
smoothScrollerStop — Dispatches at the end of a smooth scroll
- Same as smoothScrollerStart

Promises

The static scroll method returns a promise that resolves upon scroll completion. The promise includes the same data as the above event data. Awaiting the promise is the easiest way to react to the result of a smooth scroll.

damianmgarcia / SmoothScroller