useWheelToAdjust

A custom React hook that registers mouse wheel rotation from the user that start on the element referenced by dragAreaRef. This hook detects how fast the user is rotating the mouse wheel and returns a value corresponding to the speed of the mouse wheel.

This custom hooks allows for creating UI elements that can be adjusted by using the mouse wheel, such as sliders, or values that change in response to user input.

This is a lower-level custom hook that is used by useSlider and useDial.

Example

Demo

Use the mouse wheel to change!

Scroll faster for coarse adjustments, and slower for fine adjustments

0.0

Code

UseWheelToAdjust.tsx

import { useRef, useState, useEffect } from "react";
import { useWheelToAdjust } from "@gertalot/sliders";

const UseWheelToAdjustComponent = () => {
  const dragAreaRef = useRef<HTMLDivElement>(null);
  const [value, setValue] = useState(0);

  const { wheelDelta, isScrolling } = useWheelToAdjust({ dragAreaRef, sensitivity: 20 });

  useEffect(() => {
    if (isScrolling) {
      setValue((prev) => prev + wheelDelta);
    }
  }, [wheelDelta, isScrolling]);

  return (
    <div
      className="h-72 flex items-center justify-center bg-gray-900 p-0 border-white border-solid border-2 touch-none select-none"
      ref={dragAreaRef}
    >
      <div className="flex flex-col items-center space-y-2">
        <p className="text-xl">Use the mouse wheel to change!</p>
        <p className="text-center text-sm">Scroll faster for coarse adjustments, and slower for fine adjustments</p>
        <h1 className="text-2xl font-bold">{value.toFixed(1)}</h1>
      </div>
    </div>
  );
};

export default UseWheelToAdjustComponent;

Usage

const {
  dragAdjust, // a value indicating how much the user is dragging
  isDragAdjusting, // true if the user is dragging
} = useDragtoAdjust({
  dragAreaRef, // "active" element that listens to dragging actions
  sensitivity, // larger values = slower changes in output. Default is 100
  measureVerticalDragging, // true if the hook measures vertical pointer distance, false if horizontal
  dragTouches, // the number of touches on touch devices that count as dragging
});

Props

dragAreaRef

(required) A RefObject referencing a DOM element that functions as the “active” area. Any dragging or sliding action that happens when the pointer is over this element is registered as dragging the target.

sensitivity

Determines quickly the resulting value changes in response to the user dragging Higher sensitivity values result in smaller adjustments for the same dragging distance. Default value is 100.

measureVerticalDragging

Determines if this hook responds to horizontal or vertical dragging actions. Default is true.

dragTouches

For touch devices, specifies the number of touches that will register as dragging. Defaults to 2.

Returns

dragAdjust

A value corresponding to the current drag distance.

isDragAdjusting

True if the user is currently dragging.