Smooth OverlayScrollbars scroll from fixed header wheel event in React

I’m building a React application using TypeScript and overlayscrollbars-react to handle scrolling for the main content area. Above this scrollable content, I have a fixed header component (HeaderApp).

Goal:

I want the user to be able to scroll the OverlayScrollbars container even when their mouse cursor is hovering over the fixed HeaderApp. The desired scrolling behavior should be smooth, ideally matching the native feel of scrolling directly within the OverlayScrollbars viewport.

Problem:

Naturally, wheel events over the fixed header don’t scroll the underlying content. Following recommendations (like in OverlayScrollbars GitHub Issue #150), I’m capturing the wheel event on the HeaderApp, preventing its default action, and then programmatically scrolling the OverlayScrollbars container.

However, achieving smooth scrolling comparable to the native OverlayScrollbars behavior has proven difficult.

What I’ve Tried:

1. Manual Animation with requestAnimationFrame: This approach feels the
   closest, but it’s still not perfect – the scrolling can feel
   slightly jerky or disconnected from the native scroll feel,
   especially with small, single wheel movements.

Here’s the relevant code from my HeaderApp.tsx component:

// Simplified HeaderApp component structure
import React, { useRef, useEffect, useCallback } from 'react';
import type { OverlayScrollbars } from 'overlayscrollbars';
// osGlobalInstance is obtained from the ScrollableContainer component
import { osGlobalInstance } from "../ScrollableContainer/ScrollableContainer";

const HeaderApp: React.FC<HeaderAppProps> = (/*...props*/) => {
const headerRef = useRef<HTMLDivElement>(null);

// Function for smooth scroll animation
const scrollContent = useCallback((deltaY: number) => {
    if (osGlobalInstance) {
        const { scrollOffsetElement } = osGlobalInstance.elements();
        if (!scrollOffsetElement) return;

        // Cancel any previous animation frame for this specific scroll action
        // (Requires managing animation frame IDs - simplified here)
        // cancelAnimationFrame(animationFrameIdRef.current);

        const targetScrollTop = scrollOffsetElement.scrollTop + deltaY;
        const duration = 300; // Animation duration
        const start = scrollOffsetElement.scrollTop;
        const startTime = performance.now();

        const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);

        const smoothScrollStep = (currentTime: number) => {
            const elapsed = currentTime - startTime;
            const progress = Math.min(elapsed / duration, 1);
            const easing = easeOutCubic(progress);

            scrollOffsetElement.scrollTop = start + (targetScrollTop - start) * easing;

            if (progress < 1) {
               requestAnimationFrame(smoothScrollStep);
               // Store animationFrameIdRef.current = requestAnimationFrame(...)
            }
        };

        requestAnimationFrame(smoothScrollStep);
         // Store animationFrameIdRef.current = requestAnimationFrame(...)
    }
 }, []); // Dependency on osGlobalInstance if it changes

 // Wheel event handler on the header
 const handleWheel = useCallback((event: WheelEvent) => {
    if (osGlobalInstance) {
        // Prevent default page scroll and stop propagation
        if (event.cancelable) {
            event.preventDefault();
        }
        event.stopPropagation(); // Prevent event from bubbling further if needed

        // Adjust sensitivity if necessary
        const scrollAmount = event.deltaY * 1.5; // Example multiplier

        scrollContent(scrollAmount);
    }
 }, [scrollContent]); // Dependency on scrollContent

 // Attach wheel listener
 useEffect(() => {
    const headerElement = headerRef.current;
    if (headerElement && osGlobalInstance) {
        headerElement.addEventListener('wheel', handleWheel, { passive: false });
    }
    return () => {
        if (headerElement) {
            headerElement.removeEventListener('wheel', handleWheel);
        }
    };
 }, [osGlobalInstance, handleWheel]); // Dependencies

 return (
    <motion.header ref={headerRef} /* ...other props */ >
        {/* Header content */}
    </motion.header>
 );
};

export default HeaderApp;

// In ScrollableContainer.tsx (simplified):
// export let osGlobalInstance: OverlayScrollbars | null = null;
// ...
// const handleInitialized = (instance: OverlayScrollbars) => {
//     osGlobalInstance = instance;
//     // ...
// };
// ...
// <OverlayScrollbarsComponent events={{ initialized: handleInitialized }} ... >

2. Using scrollOffsetElement.scrollBy({ behavior: ‘smooth’ }): This
   seemed promising, but calling it rapidly from the stream of wheel
   events caused the browser’s smooth scroll animation to stutter and
   interrupt itself, resulting in very jerky movement. Throttling the
   calls helped slightly but didn’t fully resolve the jerkiness.

3. Using scrollOffsetElement.scrollBy({ behavior: ‘auto’ }) (with
   Throttling): This avoids the animation interruption issue, but the
   resulting scroll is instantaneous for each step, lacking the desired
   smoothness.

Question:

How can I achieve a truly smooth, native-feeling programmatic scroll of an OverlayScrollbars container triggered by wheel events on a separate fixed element (like a header) in React?

Is there a better way to implement the requestAnimationFrame loop to handle the stream of deltaY values more gracefully? (e.g., adjusting target dynamically, better cancellation).

Is there an OverlayScrollbars API feature or specific technique I’m missing for this scenario?

What is the best practice for translating high-frequency wheel events into a smooth scroll animation within a custom scroll container like OverlayScrollbars?

Any help or pointers would be greatly appreciated!