useScrollVelocity

A library that returns an immutable value that signifies the users scroll velocity.

It returns a positive float on down scroll and a negative float on up scroll behavior. The returned value is lerped, the lerp speed is 0.1 by default but can be overwritten by passing the lerpSpeed prop, if you need additional smoothing functionality you should either use your own function or use it in conjunction with ThreeJS Math utils like lerp.

Example with built in lerp:

const scrollVelocity = useScrollVelocity({ lerpSpeed: 0.3 })

Example with ThreeJS Math util:

const meshRef = React.useRef()
const lerpSpeed = 0.3
const scrollVelocity = useScrollVelocity()

const THREELerp = THREE.MathUtils.lerp(
    meshRef.current.material.uniforms.uScrollVelocity.value,
    scrollVelocity.current,
    lerpSpeed
)

Motivation

Creating animations that react to the speed of which the user scrolls can be a bit tricky. Most libraries that give this kind of functionality require you to install their entire package. This package tries to solve this by returning an immutable value that serves a singular purpose.

Installation

yarn add @kaliber/use-scroll-velocity

Usage

import { useScrollVelocity } from '@kaliber/use-scroll-velocity'

function R3FComponent() {
    const scrollVelocity = useScrollVelocity()
    const meshRef = React.useRef()

    useFrame(() => {
        const normalizedVelocity = scrollVelocity.current * 0.01
        meshRef.current.rotation.z += normalizedVelocity
    })

    return <mesh ref={meshRef}><boxMesh /></mesh>
}

Reference

This library is mainly used as an immutable state reference for ThreeJS / R3F.

Disclaimer

This library is intended for internal use, we provide no support, use at your own risk. It does not import React, but expects it to be provided, which @kaliber/build can handle for you.

This library is not transpiled.