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 calle.preventDefault
on touchMove. Defaults to false.unpreventTouchClass
: Elements with this class won'tpreventDefault
on touchMove. For instance, useful for a scrolling text inside a VirtualScroll-controled element. Defaults tovs-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 trueuseTouch
: 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.