https://github.com/ayamflow/virtual-scroll
A low-level library to create custom scroll behaviors.
https://github.com/ayamflow/virtual-scroll
Last synced: about 1 year ago
JSON representation
A low-level library to create custom scroll behaviors.
- Host: GitHub
- URL: https://github.com/ayamflow/virtual-scroll
- Owner: ayamflow
- License: mit
- Created: 2014-12-07T15:20:44.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2024-10-28T01:12:36.000Z (over 1 year ago)
- Last Synced: 2025-05-12T11:42:54.589Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 59.6 KB
- Stars: 505
- Watchers: 5
- Forks: 42
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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](http://www.everyday3d.com/blog/index.php/2014/08/18/smooth-scrolling-with-virtualscroll/) 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](https://github.com/locomotivemtl/locomotive-scroll) or [smooth-scrolling](https://github.com/baptistebriel/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](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Improving_scrolling_performance_with_passive_listeners) 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:
```js
{
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
```js
import VirtualScroll from 'virtual-scroll'
const scroller = new VirtualScroll()
scroller.on(event => {
wrapper.style.transform = `translateY(${event.y}px)`
})
```
### License
MIT.