useWheel

The useWheel hook listens to wheel gestures on a DOM element or the window, giving you scroll-like movement data with access to deltas, velocity, and raw events — perfect for zooming, panning, and gesture-driven UIs.

Syntax

useWheel(
  refs: RefObject<HTMLElement> | RefObject<HTMLElement>[] | window,
  callback: (event: WheelEvent & { index: number }) => void
): void

Parameters

Name	Type	Description
Refs (required)	RefObject<HTMLElement> or RefObject<HTMLElement>[] or Window	The element(s) or window to listen to for wheel movement.
Callback (required)	(event:WheelEvent) => void	Called on every scroll frame and gesture end.

WheelEvent Signature

type WheelEvent = {
  index: number;
  movement: { x: number; y: number };  // Delta from this event
  offset: { x: number; y: number };    // Accumulated wheel movement
  velocity: { x: number; y: number };  // Smoothed pixels/ms
  event: globalThis.WheelEvent;       // Raw native wheel event
  cancel?: () => void;                // Cancels pending gesture end timeout
};

Example: Tracking Wheel (Scroll Wheel) Events

This React example shows how to use the useWheel hook to listen to mouse wheel events on the window and track the horizontal and vertical wheel offset in real-time.

import React, { useState } from 'react';
import { useWheel } from 'react-ui-animate';

const App = () => {
  const [wheelPosition, setWheelPosition] = useState({ x: 0, y: 0 });

  useWheel(window, function (event) {
    setWheelPosition({ x: event.offset.x, y: event.offset.y });
  });

  return (
    <div style={{ height: 2000 }}>
      <div style={{ position: 'fixed', left: 10, top: 10 }}>
        WHEEL POSITION: {wheelPosition.x}, {wheelPosition.y}
      </div>
    </div>
  );
};

export default App;

Open Sandbox