scrollpro v0.0.30

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:

Options:

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

setOptions

Syntax: controller.setOptions({Options})

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

Args:

Options:

Returns: undefined

on

Syntax: controller.on(event, fn)

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

Args:

Returns: undefined

off

Syntax: controller.off(event, fn)

Removes the function passed the the on() method.

Args:

Returns: undefined

fire

Syntax: controller.fire(event)

Fires event listeners for the specified event.

Args:

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:

Options:

Returns:

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:

Options:

Returns:

createScrollbar

Syntax: controller.createScrollbar({Options})

Creates as scrollbar inside of an html element.

Args:

Options:

Returns:

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:

Options:

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:

createSticky

Syntax: contorller.createSticky({Options})

Creates a sticky element just like position sticky in css.

Args:

Options:

Returns:

scrollTo

Syntax: controller.scrollTo({Options})

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

Args:

Options:

Returns: undefined

setLimit

Syntax: controller.setLimit({Options})

Args:

Options:

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

applyTween

Syntax: applyTween(element, progress, css)

Args

Returns: undefined

applyClasses

Syntax: applyClasses(element, progress)

Args

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.