Skip to content

stevekanger/scrollpro

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

48 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

About

Momentum scrolling library

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published