README

virtual-scroll

A 2kb gzipped low-level library to create custom scrollers with touch and keyboard support. This is heavily inspired by Bartek Drozdz VirtualScroll util. See his article for reference.

Features

Can create multiple instances with different elements as targets
Let you do the actual scrolling logic: use CSS Transforms, WebGL animation or anything you like
Native arrow keys support and shift/space support mimicking default browser behaviour

For high-level libraries based off virtual-scroll, check locomotive-scroll or smooth-scrolling.

Installation

npm i virtual-scroll -S

Usage & API

Constructor

new VirtualScroll(options)
- el: the target element for mobile touch events. Defaults to window.
- mouseMultiplier: General multiplier for all mousewheel (including Firefox). Default to 1.
- touchMultiplier: Mutiply the touch action by this modifier to make scroll faster than finger movement. Defaults to 2.
- firefoxMultiplier: Firefox on Windows needs a boost, since scrolling is very slow. Defaults to 15.
- keyStep: How many pixels to move with each key press. Defaults to 120.
- preventTouch: If true, automatically call e.preventDefault on touchMove. Defaults to false.
- unpreventTouchClass: Elements with this class won't preventDefault on touchMove. For instance, useful for a scrolling text inside a VirtualScroll-controled element. Defaults to vs-touchmove-allowed.
- passive: if used, will use passive events declaration for the wheel and touch listeners. Can be true or false. Defaults to undefined.
- useKeyboard: if true, allows to use arrows to navigate, and space to jump from one screen. Defaults to true
- useTouch: if true, uses touch events to simulate scrolling. Defaults to true

Methods

instance.on(callback, context) Listen to the scroll event using the specified callback and optional context.
instance.off(callback, context) Remove the listener.
instance.destroy() Remove all events and unbind the DOM listeners.

Events note: Each instance will listen only once to any DOM listener. These listener are enabled/disabled automatically. However, it's a good practice to always call destroy() on your VirtualScroll instance, especially if you are working with a SPA.

Event

When a scroll event happens, all the listeners attached with instance.on(callback, context) will get triggered with the following event:

{
    x, // total distance scrolled on the x axis
    y, // total distance scrolled on the y axis
    deltaX, // distance scrolled since the last event on the x axis
    deltaY, // distance scrolled since the last event on the y axis
    originalEvent // the native event triggered by the pointer device or keyboard
}

Example

import VirtualScroll from 'virtual-scroll'

const scroller = new VirtualScroll()
scroller.on(event => {
    wrapper.style.transform = `translateY(${event.y}px)`
})

License

MIT.

Usage no npm install needed!