@adoratorio/hades

Hades

A smooth scrollbar with optional native scroll or section implementation for performance boosting

Installation

Hades is written in typescript and available as npm package with the alongside types definitions. So install as always

 npm install --save @adoratorio/hades

Usage

Then it can be required or imported as module

import Hades from '@adoratorio/hades';

Internally Hades is using other Adoratorio packages like Hermes for scroll event handling and normalization and Aion for requestAnimationFrame management so also those packages documentations are worth to check out.

Available options

Hades accepts in the constructor an option object with the following possible props.

Note: all options are used only in virtual mode, except of course for the mode one

parameter	type	default	description
aion	`Aion	null`	null
autoplay	boolean	true	Autostart the rendering cycle or not.
mode	string	Hades.MODE.VIRTUAL	A string indicating the scroll mode you wish to use It can be virtual, native or fake. Static enumerators are exposed to help: Note: Mode fake isn't currently implemented.
viewport	HTMLElement	document.querySelector('.hades-viewport')	DOM node used to identify the wrapper for the container. Usually it's a fixed height Element with overflow: hidden for the virtual mode. In case of native or fake modes, is the scroll container used to detect scroll events.
container	HTMLElement	document.querySelector('.hades-container')	The node translated when the user scrolls.
lockX	boolean	true	Lock the x axis when detecting scroll events.
lockY	boolean	false	Lock the y axis when detecting scroll events.
sections	`boolean	string`	false
boundaries	{ min: { x: number, y:number },max: { x:number, y:number } }	Hades.createBoundaries(xMin, xMax, yMin, yMax)	The scroll max and min amount in the x and y axis. An object containing these properties { min: { x: 0, y: 0 }, max: { x: 0, y: 0 } }. A static utility function is exposed as helper to build the object: Hades.createBoundaries(xMin, xMax, yMin, yMax).
loop	boolean	false	If sections and infiniteScroll are enabled you can create an infinite loop of section that cycle continuously. Note: Currently implemented only for x-axis ({ lockX: false, lockY: true}).
infiniteScroll	boolean	false	Whether or not the boundaries are taken into account when checking the scroll amount, resulting in an infinite scrolling on all axis.
renderScroll	boolean	fkalse	Whether or not to apply the actual CSS transform property. If false the internal amount is kept and exposed for your personal use.
callbacks	{ Callback, Callback }	{frame: () => {}, scroll: () => {} }	The scroll function is called each scroll event. The frame function is called every rAF after updating style.
emitGlobal	boolean	false	If you want that the custom-scroll generated internally also emit on global scope (window).
startStopPrecision	number	4	A number to define the precision of the start and stop events.
renderByPixel	boolean	false	Used if you want to apply integer rounded values to the css transition units. If false, the full value is used, resulting in smoother animations, especially the slowest ones. This avoids stuttering especially at the end of the animation, but its performance consuming.
duration	number	1000	The total duration of the scrolling inertia after the user has stopped scrolling. Expressed in ms.
easing	Function	Hades.EASING.LINEAR	A function used to bend the progress over time to match a curve and create more natural scrolling inertia. The function is called with a single parameter being the time normalized in relation with the total duration (currentTime / totalDuration) so the value is going from 0 to 1. Eg. for a linear time function(t) { return t; }. It's always a advised to use a linear-in eased-out timing function to avoid weird visual artifacts when the scroll starts. Some enumerators are exposed, just for having a bunch of useful functions out of the box. If you wish BezierEasing from bezier-easing npm package can be used as easing function.
touchMultiplier	number	1.5	A multiplier for calculating the delta of touches and the speed, passed to Hermes. Reasonable values are between 0.8 and 3 but it's just a suggestion. Higher values will increase the feeling of slippery touch effect.
smoothDirectionChange	boolean	false	If true when the scroll direction change the easing setted is kept to help the transition between one direction and the other to feel more inertia. On really smooth easing and high durations this can feel a bit awkward. If false an immediate direction change is applied.

APIs

Static Property

EASING

. Hades.EASING.LINEAR
. Hades.EASING.QUAD
. Hades.EASING.CUBIC
. Hades.EASING.QUART
. Hades.EASING.QUINT

MODE

• Hades.MODE.VIRTUAL
• Hades.MODE.NATIVE
• Hades.MODE.FAKE

DIRECTION

• Hades.DIRECTION.UP
• Hades.DIRRECTION.DOWN
• Hades.DIRECTION.INITIAL

Static Methods

Hades.createBoundaries(xMin, xMax, yMin, yMax)

Hades.createBoundires(xMin: number, xMax: number, yMin: number, yMax: number): Boundaries

Create an object that fits the scrollbar boundaries.

Instance Properties

The Hades instance exposes two main properties:

amount

• Type: interface Vec2 { x:number, y:number } With x and y props exposes the current scroll amount, updated frame-by-frame.

velocity

• Type: interface Vec2 { x:number, y:number } With x and y props exposes the current scroll speed, updated frame-by-frame.

Instance Getters

direction

• Type number Get the current direction of the scroll.

• Page moving up is 1
• Page moving down is -1.

Enumerators are also exposed with Hades.DIRECTION.UP, Hades.DIRECTION.DOWN and an inert enum is exposed Hades.DIRECTION.INITIAL.

virtual

• Type boolean Get true if mode is set to virtual or false if not.

native

• Type boolean Get true if mode is set to native or false if not.

fake

• Type boolean Get true if mode is set to native or false if not.

Instance Setters

easing

• Type object Set the easing object. The object contain two params:

• the easing mode
• the easing duration

Use the constructor param for the documentation reference of both params

infiniteScroll

• Type boolean Set if infinite scroll is used or not, use the constructor param for documentation reference.

emitGlobal

• Type boolean Set if global events are emitted or not.

boundaries

• Type Boundaries Set a new boundaries to control the scroll max and min amount in the x and y axis.

touchMultiplier

• Type number Set the touch multiplier passed to Hermes instance.

smoothDirectionChange

• Type boolean Set whether to use smooth direction change or not.

renderScroll

• Type boolean Set if to apply CSS transform or not.