Advanced Smooth Scrolling For Web Apps – FluidScroll.js

FluidScroll is an advanced and highly customizable smooth scrolling JavaScript library designed for websites featuring long pages, single-page applications, or sections that demand smooth transitions.

This library can help you handle various scrolling scenarios on your web project. You can smoothly scroll to specific pixel coordinates, the top or bottom of the page, or even relative positions. This control allows for precise navigation within a webpage.

Comparison with CSS scroll-behavior:

While CSS scroll-behavior: smooth; provides a basic level of smooth scrolling, FluidScroll provides more control and flexibilities:

• Full browser compatibility
• Control over animation timing and easing
• Support for both axis scrolling
• Customizable scroll destinations
• Animation interruption handling
• Callback functions
• Element-based scrolling targets
• Relative position scrolling

How to use it:

1. Download & Install with NPM.

# NPM
$ npm install fluidscroll

2. import fluidscroll into your project.

// ES Module
import { fluidScroll } from 'fluidscroll';
// CommonJS
const fluidScroll = require('fluidscroll');

<!-- OR -->
<script src="../dist/fluidscroll.umd.js"></script>

3. Here are some basic examples:

// Scroll to y-position 1000px over 1000 milliseconds
fluidScroll({
  yPos: 1000, 
  duration: 1000
});
// Scroll to the bottom of the page
fluidScroll({
  yPos: 'end'
});
// Scroll to x-position 500px and y-position 500px
fluidScroll({
  xPos: 500, 
  yPos: 500
});
// Scroll to the center of the container you specify
fluidScroll({
  yPos: 'center', 
  scrollingElement: container
});

4. Available configuration options to customize the scrolling behavior:

• yPos: Controls vertical scrolling. Accepts absolute pixels, relative distances (‘+100’, ‘-50’), percentages (‘+10%’, ‘-15%’), or keywords (‘start’, ‘center’, ‘end’)
• xPos: Controls horizontal scrolling. Uses same format as yPos
• duration: Animation time in milliseconds
• scrollingElement: Target element for scrolling
• toElement: Scroll to specific HTML element
• preventUserScroll: Blocks user scrolling during animation
• easing: Animation timing function
• complete: Callback function after animation
• firstAxis: Priority axis for simultaneous scrolling
• block: Element position relative to container top
• inline: Element position relative to container left
• paddingTop/paddingLeft: Additional offset pixels
• scrollEvents: Events that stop the animation if preventUserScroll is false.
• scrollKeys: Key codes that stop the animation if preventUserScroll is false.
• allowAnimationOverlap: Allow multiple animations on the same container.

fluidScroll({
  yPos: '',
  xPos: '',
  duration: 500,
  scrollingElement: '',
  toElement: ''
  preventUserScroll: true,
  easing: 'linear',
  complete: null,
  firstAxis: '',
  block: '',
  inline: '',
  paddingTop: '',
  paddingLeft: '',
  scrollEvents: ['scroll', 'mousedown', 'wheel', 'DOMMouseScroll', 'mousewheel', 'touchmove'],
  scrollKeys: [37, 38, 39, 40, 32],
  allowAnimationOverlap: false,
});

5. Additional API Methods:

// Remove instance
instance.destroy();
// Get/set default options
fluidScroll.defaults();
fluidScroll.defaults(options);
// Control animations
fluidScroll.stopAll();
fluidScroll.scrolling();
// Check browser support
fluidScroll.nativeSupported;
// Access easing functions
fluidScroll.easing;