ayamflow/virtual-scroll

A low-level library to create custom scroll behaviors.

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.

virtual-scroll's Issues

Edge Bug

Do you try this on Microsoft Edge?
seems don't work

Example Next.js Typescript Hook

Hey, just leaving this Issue here for anyone wanting to write this as a Next.js Typescript hook.

1. In src/support.js, make sure to check for process.browser or you'll get a document is undefined error. This is due to SSR, I think.

const getSupport = () => {
  if (process.browser) {
    return {
      hasWheelEvent: "onwheel" in document,
      hasMouseWheelEvent: "onmousewheel" in document,
      hasTouch: "ontouchstart" in document,
      hasTouchWin: navigator.msMaxTouchPoints && navigator.msMaxTouchPoints > 1,
      hasPointer: !!window.navigator.msPointerEnabled,
      hasKeyDown: "onkeydown" in document,
      isFirefox: navigator.userAgent.indexOf("Firefox") > -1,
    }
  }
}

export default getSupport

2. Hook :

import VirtualScroll from "libs/virtual-scroll/src/index"
import { useEffect, MutableRefObject } from "react"

export type VirtualScrollEvent = {
  x: number // total distance scrolled on the x axis
  y: number // total distance scrolled on the y axis
  deltaX: number // distance scrolled since the last event on the x axis
  deltaY: number // distance scrolled since the last event on the y axis
  originalEvent: Event // the native event triggered by the pointer device or keyboard
}
type VirtualScrollCallback = (e: VirtualScrollEvent) => void

const useVirtualScroll = (
  ref: MutableRefObject<HTMLElement>,
  callback: VirtualScrollCallback,
  dependencies: any = [],
) => {
  useEffect(() => {
    if (ref.current) {
      const instance = new VirtualScroll(ref.current)
      instance.on((e: VirtualScrollEvent) => callback(e))

      return () => {
        instance.destroy()
      }
    }
  }, dependencies)

  return typeof window !== "undefined"
}

export default useVirtualScroll

3. Usage:

import useVirtualScroll, { VirtualScrollEvent } from "hooks/useVirtualScroll"

const HomeView: FC<Props> = ({ home, descriptionContent }) => {
  const testRef= useRef(null)
  const onVirtualScroll = (e: VirtualScrollEvent) => {
    console.log(e)
  }
  useVirtualScroll(testRef, onVirtualScroll, [testRef.current])

  return (
    <div ref={testRef}></div>
  )

Ivy compiler compatibility

Are you planning to add support for Ivy compiler?
Currently in Angular 13+ we need to do npm i --force to make this package work.

Thank you,
Shiva

Roadmap

• make it work 👍
• add support for real scrollbar
• fallback without scrollbar on iOS<8 & stuff

Broken when scroll back to top

Hi,

It seems that if I scroll down the page, VirtualScroll is working fine, by applying the inline transform to the wrapper.

However, if I scroll back up to the top of the page after previously scrolling downward, for some reason the inline transform value on the wrapper just keeps decreasing infinitely (see screenshot). This inline value just keeps adjusting itself, despite no scroll movement.

Thank you in advance!

VirtualScroll is not defined

I'm getting " VirtualScroll is not defined " on

VirtualScroll.on(function(e) { .... <-- This line
// Code here
}

Running ES6

What have I missed?

firefoxMultiplier for Macs

Is there a work around for getting the firefoxMultiplier working on Macs using Firefox?

It is not working at all. I would like an example of how to use it.

I want to apply it to Logio.

npm i virtual-scroll -S
var section = document.querySelector('.log_screen.active .msg')
> <div class="msg">...</div>
var scroll = new VirtualScroll({el: section})

There is no change.
Should we do something more?

Compiled script in npm registry

It would be nice to have access to a compiled version of this repo to be able to import in CDNJS.
At the moment, src/index.js cannot be imported by CodePen or JSFiddle because it cannot resolve his dependencies.

Thanks

Fake Scrollbar with `scroll` event?

Any idea how I would add a fake scroll bar which has the same functionality as a normal one (move scrollbar thumb, scroll content on scrollbar drag)?

I already have the fake scrollbar implemented which will be animated in the requestAnimationFrame to the same value as the content. But then I can't drag the scrollbar because it will be immediately updated by the requestAnimationFrame .

Would be nice to have a hint or an example. :)
Thanks!

Integration with GSAP ScrollTrigger

Hi,

I tried to implement it with gsap, following are my feelings:
1- There is no demo.
2- It felt quite choppy or not smooth at all. It's like I am jumping just 120px.
3- How to integrate it with GSAP and ScrollTrigger.
4- There is a destroy event to call on page switch when using SPA. But I don't see the option to update it or enable it for the next page like with other libraries.

Regards
Shehzad Asif

Is there anyway to check when scroll stops using the .on() method?

I'm trying to add a class to the body (i.e. .is-scrolling) and remove it when scrolling stops. Can't figure it out.

Thanks

IE Edge trackpad problem

the virualscroll don't work with trackpad on IE Edge, dou you have an idea ? or its a known bug ?
Thx a lot for your work

Github lists 2.0.0 as latest release

Hi there, it looks like you are up to 2.2.1 but Github is still showing 2.0.0 as the latest release when you browse the project.

Add option to disabled keyboard control

Hi and thx for your work,
I think to have the possibility to disabled keayboard control will be usefull for some project.
(put a keyStep option to 0 do the job for me)
Thx

Issue with mobile device

I have this site

mirror.studiomonocromo.it/it/about

seems that with mobile device android the page don't scroll down, why?

Cheers

Check accessibility / Other ways to trigger scroll

For instance space / ctrl + space, ctrl + up/down... and see if we can get those events or fake them

How to disable virtual-scroll for touch-devices?

Hello,

how can I disable virtual-scroll on all kind of touch devices?

Thank you,
Mathias

Allow to pass a custom element as event target

Currently window & document are used, which can cause issues when using multiples instances of VirtualScroll for instance.

Issue on Firefox with trackpad

I realized this because of using locomotive scroll and thought the issue is there, but they use virtual-scroll and for me it looks like the issue lays in following line:

virtual-scroll/src/index.js

Line 83 in 4763533

evt.deltaY = e.wheelDeltaY || e.deltaY * -1

Basically, if I'm in Firefox and using a trackpad, the scrolling is way too fast.

if I only use
evt.deltaY = e.deltaY * -1;
instead of
evt.deltaY = e.wheelDeltaY || e.deltaY * -1;

it looks like it's the same behaviour as in chrome again, so maybe somethin inside Firefox changed regarding wheelDeltaY or something

Start Scroll Event

Hi and thx for your work.
I need a bullet proof "start scroll event" for my scroll implementation, do you have any idea to simulate this ?
Thx