FluidScroll

A cross-browser compatible, lightweight, easy-to-use library for smooth scrolling.

fluidScroll({ options });

Installation

This library can be installed with NPM.

npm i fluidscroll

Then, it may be used in this manner:

// ES Module
import { fluidScroll } from 'fluidscroll';

// CommonJS
const fluidScroll = require('fluidscroll');

Alternatively, it can be directly included as a script on any HTML page. For example, with a CDN:

<script src="https://cdn.jsdelivr.net/npm/[email protected]" integrity="sha384-ZvfwaJZFftLPOaPS13spccPYdWRcrfz/GDgUYAf7b6I2OBXY74KiAC6WVg0XF3Qq" crossorigin="anonymous"></script>

You can also manually download dist/fluidscroll.umd.min.js and include it in the head of the page using your own path:

<script src="path/to/fluidscroll.min.js"></script>

It can additionally be used in a module script:

<script type="module">
    import { fluidScroll } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/fluidscroll.esm.mjs';
</script>

Import maps can furthermore be used to simplify the module specifier when importing as well as check the integrity.

<script type="importmap">
    {
        "imports": {
            "fluidscroll": "https://cdn.jsdelivr.net/npm/[email protected]/dist/fluidscroll.esm.mjs"
        },
        "integrity": {
            "https://cdn.jsdelivr.net/npm/[email protected]/dist/fluidscroll.esm.mjs": "sha384-uRZwvJLM1xS19wbYkR8/uqMLzM58mVHEluImXjOaBV4H3LerGAjCSGbQfBYrpNCQ"
        }
    }
</script>
<script type="module">
    import { fluidScroll } from 'fluidscroll';
</script>

Simple Uses

Scroll to y-position 1000px in 750 milliseconds:

fluidScroll({yPos: 1000, duration: 750});

Scroll to the bottom of the page:

fluidScroll({yPos: 'end'});

Scroll to x-position 500px and y-position 500px:

fluidScroll({xPos: 500, yPos: 500});

Options

Option	Description	Default
yPos	The y-position to scroll to. If specified as a number, it is an absolute number of pixels from the top. It can also be specified as a relative amount from the current position. It can also be the special string values "start" (the top of the scrolling area), "center" (the middle of the scrolling area), and "end" (the bottom of the scrolling area). A relative number of pixels is specified as a string prefixed with + (to scroll down a certain number of pixels) or - (to scroll up a certain number of pixels), e.g. '+100', '-50'. A relative percentage is specified by further adding the % symbol to the end of the string, which indicates scrolling by a percentage of the entire height, e.g. '+10%', '-15%'.	No default.
xPos	The x-position to scroll to. If specified as a number, it is an absolute number of pixels from the left. It can also be specified as a relative amount from the current position. It can also be the special string values "start" (the left of the scrolling area), "center" (the middle of the scrolling area), and "end" (the right of the scrolling area). A relative number of pixels is specified as a string prefixed with + (to scroll down a certain number of pixels) or - (to scroll up a certain number of pixels), e.g. '+100', '-50'. A relative percentage is specified by further adding the % symbol to the end of the string, which indicates scrolling by a percentage of the entire width, e.g. '+10%', '-15%'.	No default.
duration	The amount of time the scrolling takes (in milliseconds).	500
scrollingElement	The HTML element to scroll instead of the window.	No default.
toElement	The HTML element to scroll to. This option overrides the xPos and yPos options.	No default.
preventUserScroll	Prevent the user from scrolling during the smooth scroll animation.	true
easing	The easing function. It can either be a string that is the name of one of the predefined easing functions (in fluidScroll.easing), or a function that accepts the percentage of time that has passed (in its decimal form, between 0 and 1) and returns the percentage of the scrolling distance to scroll to at the current time (as a number between 0 and 1).	'linear'
complete	The callback function to invoke when the smooth scrolling is complete.	No default.
firstAxis	The first axis to scroll if changing both the x- and y-positions. There are two possible values: 'x' and 'y'. If not specified, both axes will scroll at the same time.	No default.
scrollEvents	An array of strings indicating the names of events that will stop the scrolling animation if the preventUserScroll option is set to false.	['scroll', 'mousedown', 'wheel', 'DOMMouseScroll', 'mousewheel', 'touchmove']
scrollKeys	An array of integer key codes represent the keys that will stop the scrolling animation when pressed by the user if the preventUserScroll option is set to false.	[37, 38, 39, 40, 32]
block	The position of the element of the element to scroll to (specified by the toElement option) relative to the top of the container. The value can be "start" (the top of the element is aligned to the top of the visible area), "center" (the element is in the vertical center of the visible area), "end" (the bottom of the element is aligned with the bottom of the visible area), or a string indicating the percentage, e.g. '50%'. If not specified, it is the same as "start".	No default.
inline	The position of the element of the element to scroll to (specified by the toElement option) relative to the left of the container. The value can be "start" (the left of the element is aligned to the left of the visible area), "center" (the element is in the horizontal center of the visible area), "end" (the right of the element is aligned with the right of the visible area), or a string indicating the percentage, e.g. '50%'. If not specified, it is the same as "start".	No default.
allowAnimationOverlap	A boolean value indicating whether or not multiple simultaneous animations are allowed on the same container.	false
paddingTop	A certain number of pixels to add to the y-position to scroll to. If not specified, it is the same as 0.	No default.
paddingLeft	A certain number of pixels to add to the x-position to scroll to. If not specified, it is the same as 0.	No default.

Return Value

fluidScroll returns an object with the destroy property which is a function that stops the scrolling when called.

var s = fluidScroll({yPos: 5000, duration: 3000});
// Stop the scrolling sometime later
s.destroy();

Instantiation

Using the new operator will create an instance with the passed in options as defaults. Properties specified in this options object will override the original defaults. Call the fluidScroll method on the returned value to perform smooth scrolling with these defaults.

var scroller = new fluidScroll({duration: 700, block: 'center'});
scroller.fluidScroll({yPos: 500}); // duration is 700 (rather than the original default of 500)

Getting and Setting Global Defaults

fluidScroll.defaults() returns an object containing the default values for each option.
Passing an object to fluidScroll.defaults will overwrite each option in the defaults with the value from that object if it is set.

fluidScroll.defaults({duration: 700}); // set default duration to 700ms

Other Methods and Properties

fluidScroll.stopAll() stops all current scroll animations and returns true/false depending on whether there were running animations that were stopped.

fluidScroll.scrolling() returns true/false depending on whether or not there are current scrolling animations.

fluidScroll.nativeSupported indicates whether or not the CSS scroll-behavior property is supported in the current browser.

fluidScroll.easing is an object containing the predefined easing functions.

Examples

Examples of common use cases can be found in the examples folder. These can be run by cloning the repository, then opening any of the HTML files in a browser. Note that many newer JavaScript features are not used in order to demonstrate more cross-browser compatible code.