ScrollPro

Smooth momentum scrolling library. Check it out in action. ScrollPro Example

Disclaimer: As of now nested instances has partial support. Nested scrollbars may not work as intended.

Installation

npm install scrollpro

Usage

Simple momentum scrolling with content and scrollbar

JS

import Controller from 'scrollpro'

const ctl = new Controller()
const viewport = ctl.createViewport()

const contentEl = document.getElementById('content')
const content = ctl.createContent({ element: contentEl })

const scrollbarEl = document.getElementById('content')
const scrollbar = ctl.createScrollbar({ element: scrollbarEl })

Css

There will be a couple of elements that will be added to your scrollbar element .track and .bar but there is no default css added to the scrollbar element you provide and no colors added to the .bar. You will need to style it yourself so you can customize it to your liking.

#scrollbar {
  position: fixed;
  top: 0;
  right: 0;
  width: 15px;
  height: 100%;
  z-index: 9999;
  background: #f0f0f0;
}

#scrollbar .bar {
  background: #c8c8c8;
}

Good practice to add a clearfix or an overflow property to the container to ensure margins are calculated.

#content:before,
#content:after {
  display: block;
  clear: both;
  content: '\a0 ';
  visibility: hidden;
  height: 0;
}

HTML

<div id="scrollbar"></div>
<div id="content"></div>

Adding a custom viewport to above example

JS

import Controller from 'scrollpro'

const ctl = new Controller()
const viewportEl = document.getElementById('viewport')
const viewport = ctl.createViewport({ element: viewportEl })

const contentEl = document.getElementById('content')
const content = ctl.createContent({ element: contentEl })

const scrollbarEl = document.getElementById('content')
const scrollbar = ctl.createScrollbar({ element: scrollbarEl })

Css

#viewport {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  overflow: hidden;
}

HTML

<div id="scrollbar"></div>
<div id="viewport">
  <div id="content"></div>
</div>

Creating a controller

Syntax: new Controller({Options})

Args:

Argument	Required	Type	Description
ControllerOptions	false	Object	Parameters for virtual scrolling

Options:

Option	Type	Default	Description
keystep	number	120	The amount in px you want to scroll when the up and down keys are pressed
firefoxMult	number	25	The speed multiplier used for firefox browser
touchMult	number	2	The speed multiplier used for touch screens
mouseMult	number	1	The speed multiplier used for the mouse wheel
ease	number	0.1	The ease value of the scroll container. The speed that the container comes to a stop.
disableKeyNavigation	boolean	false	If you want to disable the ability to scroll with the keyboard eg. pageup and pagedown buttons ect.

Controller Events

update : fires when the controller updates the scroll. This event will be called with the scroll values.
init : fires when the createViewport is called initializing the controllers event listeners.
refresh: fires when refresh is called. This can be called via the controller methods or will fire automatically when the window resizes.
kill : fires then the controller is killed.

Public Controller Methods

getScroll

Syntax: controller.getScroll()

Gets the current scroll values.

Args: none

Returns: Scroll

value	type	Description
scrollX	number	The current scroll value of the x axis.
scrollY	number	The current scroll value of the y axis.
deltaX	number	The scrollX value will animate until it reaches this value.
deltaY	number	The scrollY value will animate until it reaches this value.
limitX	number	This is the limit the scrollX can get to. If you don't have content set or manually set a limit this will be Infinity.
limitY	number	This is the limit the scrollY can get to. If you don't have content set or manually set a limit this will be Infinity.
progressX	number	This is the progress the scrollX has made relative to the limitX from 0 to 1.
progressY	number	This is the progress the scrollY has made relative to the limitY from 0 to 1

setOptions

Syntax: controller.setOptions({Options})

Sets controller options. It will combine the already set options with the options you pass in.

Args:

Argument	Required	Type	Description
ControllerOptions	true	Object	Parameters for virtual scrolling

Options:

Option	Type	Default	Description
keystep	number	120	The amount in px you want to scroll when the up and down keys are pressed
firefoxMult	number	25	The speed multiplier used for firefox browser
touchMult	number	2	The speed multiplier used for touch screens
mouseMult	number	1	The speed multiplier used for the mouse wheel
ease	number	0.1	The ease value of the scroll container. The speed that the container comes to a stop.
disableKeyNavigation	boolean	false	If you want to disable the ability to scroll with the keyboard eg. pageup and pagedown buttons ect.

Returns: undefined

on

Syntax: controller.on(event, fn)

Allows you to set event listeners for the controller events stated above.

Args:

Argument	Required	Type	Description
event	true	string	The desired event type for your function to be fired on.
fn	true	function	The desired function to be run on the event.

Returns: undefined

off

Syntax: controller.off(event, fn)

Removes the function passed the the on() method.

Args:

Argument	Required	Type	Description
event	true	string	The desired event type for your function to be fired on.
fn	true	function	The desired function to be run on the event.

Returns: undefined

fire

Syntax: controller.fire(event)

Fires event listeners for the specified event.

Args:

Argument	Required	Type	Description
event	true	string	The desired event type for your function to be fired on.

Returns: undefined

kill

Syntax: controller.kill()

Kills the controller. Removes all event listeners from the viewport and removes all scroll listeners from the controller.

Args: none.

Returns: undefined

refresh

Syntax: controller.refresh()

Recalculates the controller and all items in the controller. This will fire automatically when the window resizes and when the documents fonts are loaded.

Args: none

Returns: undefined

update

Syntax: controller.update()

Updates the controller items with the current scroll values.

Args: none

Returns: undefined

createViewport

Syntax: controller.createViewort({Options})

Creates the viewport. This initializes the controller and sets the required event listeners for virtualized scrolling.

Args:

Argument	Required	Type	Description
ViewportOptions	false	Object	Parameters for the viewport

Options:

Option	Required	Default	Type	Description
element	false	window	HTMLElement or window	Optional element to use as the viewport for the scroll controller
eventTarget	false	viewport element	HTMLElement or window	This is if you want the virtual scrolling event listeners to listen for something other than the viewport.

Returns:

value	type	Description
getBounds	function	returns the bounds of the viewport.
kill	function	kills the viewport.
refresh	function	Recalculates the bounds of the viewport

createContent

Syntax: controller.createContent({Options})

Creates the content. This is the div that will be translated up and down when virtual scrolling happens. It will also serve as the scrolling limit.

Args:

Argument	Required	Type	Description
ContentOptions	true	Object	Parameters for the content

Options:

Option	Required	Default	Type	Description
element	true	null	HTMLElement	Element to use as the content wrapper.

Returns:

value	type	Description
init	function	Initializes the content. This will be automatically called during init.
kill	function	Kills the content and removes it from event list.
refresh	function	Recalculates the content and sets new scroll limits.
update	function	Updates the content position with the current scroll values.

createScrollbar

Syntax: controller.createScrollbar({Options})

Creates as scrollbar inside of an html element.

Args:

Argument	Required	Type	Description
ScrollbarOptions	true	Object	Parameters for the Scrollbar

Options:

Option	Required	Default	Type	Description
element	true	null	HTMLElement	Element to use as the scrollbar wrapper.
axis	false	'y'	string	This is the axis you want to use as the basis for the scrollbar. 'y' is scrollY and 'x' is scrollX.
orientation	false	'vertical'	string	This is which direction your scrollbar is oriented. Top to bottom 'vertical'. Side to side 'horizontal'
useEasing	false	true	boolean	This is whether or not you want your scrollbar to use the same scrolling easing effect as the scroll uses.

Returns:

value	type	Description
setOptions	function	Sets the options. Will combine already set options.
init	function	Initializes the scrollbar. This will automatically be called during intialization.
kill	function	Kills the scrollbar removing it from the event list.
refresh	function	Recalculates the scrollbar and updates it.
update	function	Updates the scrollbar thumb with the current scroll values.

createObserver

Syntax: contorller.createObserver({Options})

Creates an observer for an html element. This will observe the elements place in the scroll relative to the viewport. Avoid placing observers inside of sticky elements or other observers.

Args:

Argument	Required	Type	Description
ObserverOptions	true	Object	Parameters for the Observer

Options:

Option	Required	Default	Type	Description
element	true	null	HTMLElement	Element to observe in the scroll
normalizeInitialView	false	false	boolean	This normalizes the start and end values of the observer. This is handy for uniform parallax scrolling if your element starts in the initial viewport.
offsetStart	false	0	number	This sets an offset from the start of the observation.
offsetEnd	false	0	number	This sets an offset from the end of the observation.
start	false	undefined	number	If you want to manually set the start of the observation this value will be used instead of calculating it.
distance	false	undefined	number	If you want to manullly set the distance for your element to be observed for this will be used intead of calculating it.
callback	false	() => {}	function	This is a callback function that will be fired every time the scroll is updated and is also fired when the observer is constructed to ensure the element is in it's original start position. It is called with an object that contains {element, progress, applyClasses, applyTween} see Observer Callback Event for further documentation.

You have the ability to set up a tween on scroll with the observer. See Tweening for further details on how to set up a tween element.

Returns:

value	type	Description
setOptions	function	Sets the options. Will combine already set options.
init	function	Initializes the observer. This will automatically be called during intialization.
kill	function	Kills the observer removing it from the event list.
refresh	function	Recalculates the observer and updates it.
update	function	Updates the observer with the current scroll values.

createSticky

Syntax: contorller.createSticky({Options})

Creates a sticky element just like position sticky in css.

Args:

Argument	Required	Type	Description
StickyOptions	true	Object	Parameters for the Sticky element

Options:

Option	Required	Default	Type	Description
top	false	0	number	Sets the distance from the top the item will stick
bottom	false	0	number	Sets the distance from the bottom the item will stop sticking
start	false	undefined	number	If you want to set the start position that the element will start to stick it will use this instead of calculating
distance	false	undefined	number	If you want to set the distance the item will stick for it will use this instead of calculating.
ignoreBounds	false	false	boolean	Whether you want your sticky element to stay within the parents bounds. If set to true it will stick to the top all the way down.

Returns:

value	type	Description
setOptions	function	Sets the options. Will combine already set options.
init	function	Initializes the sticky element. This will automatically be called during intialization.
kill	function	Kills the sticky element removing it from the event list.
refresh	function	Recalculates the sticky element and updates it.
update	function	Updates the sticky element with the current scroll values.

scrollTo

Syntax: controller.scrollTo({Options})

Allows you to scroll to a specific part of the page.

Args:

Argument	Required	Type	Description
ScrollToOptions	true	Object	Parameters specifiying where you want to scroll

Options:

Option	Required	Default	Type	Description
x	false	undefined	number	Sets the x axis scroll
y	false	undefined	number	Sets the y axis scroll
ease	false	true	boolean or number	Whether or not you want to use easing when calling this method. You can set this to true, false, or an easing value from 0 - 1 and will be used instead of the Controllers easing value. This is handy if you want to speed up or slow down the easing effect when calling the scrollTo() method. Think of this as the duration of the scroll effect.

Returns: undefined

setLimit

Syntax: controller.setLimit({Options})

Args:

Argument	Required	Type	Description
SetLimitOptions	true	Object	Sets the scrolling limit

Options:

Option	Required	Default	Type	Description
x	false	undefined	number	Sets the x axis limit
y	false	undefined	number	Sets the y axis limit

Returns: undefined

Tweening

A little extra explaination on how to tween. The observer callback is called with an object that contains the following {element, progress, applyClasses, applyTween}. With these have what we need to set up a tween. To do so you can call the applyTween function with your element, the progress, and an object with valid javascript css keys and string values. The values must be in string format and in the string you can define from and to values for tweening inside curly braces separated by a comma. So something like { transform: 'translateY({0, 200}px)' }. As you can see in curly braces is {0, 500}. This will translateY from 0 to 500px. There is no limit to how many times in a string you can define curly braces or what css properties you want to tween as long as you place a from and to value in curly braces. For example if you have a css matrix you can do matrix(1, 0, 0, 1, {0, 500}, {300, 500}). This will translate the element from 0 to 500 on the x axis and 300 to 500 on the y axis. It is noteworthy to state that the from value set will override any default css values set. Also if you are going to translate up or down then you may want to replace the elements distance traveled in the offset so the element keeps translating out of frame.

Creating a tween

To create a tween we first need to create an observer. Then in the callback we can grab the applyTween function to apply our tween to whatever element we would like to apply it to. So in the example below we will just use the observer element as the tween element but you can tween whatever element you want.

const observerElement = document.getElementById('tween')
const observer = ctl.createObserver({
  element: observerElement,
  offsetEnd: -500, // Replace the 500px movement at the end of the observation.
  callback: ({element, progress, applyTween}) => {
    applyTween(element, progress, {
      width: '{200, 500}px'
      transform: 'translateY({0, 500}px) rotate({0, 90}deg)'
    })
  }
})

So in the above example we have set up our tween to translate our observed element from 0 to 500px, rotate from 0 to 90deg, and increase the width from 200 to 500 px. We alse added an offsetEnd of -500 so our tween will translate all the way through the viewport. You can also apply a tween to a different element using your observer as a trigger. There are a lot of possibilities here.

Adding classes

You can apply classes based on your elements position to the viewport. The applyClasses function will apply the following classes aboveViewport, belowViewport, and inViewport when the observer hits the respective place relative to the viewport.

const observerElement = document.getElementById('tween')
const observer = ctl.createObserver({
  element: observerElement,
  callback: ({ element, progress, applyClasses }) => {
    applyClasses(element, progress)
  },
})

Observer Callback Event

Value	Type	Description
element	HTMLElement	This is the element being observed.
progress	number	This is the current progress of the element through the viewport from 0 to 1.
applyClases	function	A function that applies classes to an element based on progress. Defined below.
applyTween	function	A function to apply a tween to an element based on progress. Defined below

applyTween

Syntax: applyTween(element, progress, css)

Args

Argument	Required	Type	Description
element	true	HTMLElement	The element you want your tween to be applied to.
progress	true	number	The current progress of your tween animation from 0 to 1.
css	true	object	This is an object of javascript valid css properties and string values. See Tweening for more details on how to set up your tweens.

Returns: undefined

applyClasses

Syntax: applyClasses(element, progress)

Args

Argument	Required	Type	Description
element	true	HTMLElement	The element you want your classes to be applied to.
progress	true	number	The current progress of your element from 0 to 1.

Returns: undefined

Note: just remember when using things like widths, margins, and things that can affect the page flow you can create performance and page breaking issues. Performance wise it is best to stick to css transform.

License

Distributed under the MIT License. See LICENSE for more information.