Skip to content
A CommonJS fork of Bartek Drozdz VirtualScroll utility
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Add useTouch to go with previously added useKeyboard, updated readme Jul 9, 2019
.gitignore Initial commit - rewrite of the base library using tiny-emitter and d… Dec 7, 2014
LICENSE Initial commit Dec 7, 2014 Add useTouch to go with previously added useKeyboard, updated readme Jul 9, 2019
package.json bump to 1.5.1 Jul 9, 2019


Custom scroll event with inertia/momentum, touch (works on <=iOS7) and keyboard compatible. This is a fork of Bartek Drozdz VirtualScroll util. See his article for a complete description.

Goals of the fork

  • Easier to add in a CommonJS / require environment
  • Enable to create several distinct instances by using a prototype rather than a singleton
  • Add some extra features
  • modules (using a dedicated Emitter for instance)


npm i virtual-scroll -S

Usage & API

For in-depth usage and tutorial, you can check Bartek's article (link above).

  • new VirtualScroll(options) Return a new instance of VirtualScroll. See the options below.

  • instance.on(fn, context) Listen to the scroll event using the specified function (fn) and optional context.

  •, context) Remove the listener.

  • instance.destroy() Will 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.


  • 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.
  • limitInertia: if true, will leverage Lethargy to avoid everlasting scroll events (mostly on Apple Mouse, Trackpad, and free-wheel mouse). Defaults to false.
  • 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



You can’t perform that action at this time.