Menu Interactions

Pointer, Wheel and Touch Interactions

ScrollMenu has two callback shapes. Getting this wrong is the #1 input bug:

• onWheel / onScroll are plain callbacks: (api, event) => void
• ALL mouse and touch props (onMouseDown, onMouseUp, onMouseMove, onMouseLeave, onTouchStart, onTouchMove, onTouchEnd) are handler factories: (api) => (event) => void. ScrollMenu invokes the factory with the api during render and attaches the returned function as the DOM handler.

All wheel/mouse/touch handlers attach to the outermost wrapper div (so they also fire over arrows, Header and Footer); onScroll attaches to the scroll container itself (src/index.tsx:319-347). api is the same publicApiType object that VisibilityContext provides.

Touch devices scroll the menu natively — no touch props are needed for basic mobile swipe. Drag-to-scroll below is the desktop "swipe" equivalent.

Setup

Both shapes wired on a minimal menu:

tsxCopy code
import React from 'react';
import {
  ScrollMenu,
  VisibilityContext,
  type publicApiType,
} from 'react-horizontal-scrolling-menu';
import 'react-horizontal-scrolling-menu/dist/styles.css';

function Card({ itemId }: { itemId: string }) {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const visible = api.useIsVisible(itemId, true);
  return <div style={{ width: 160, opacity: visible ? 1 : 0.5 }}>{itemId}</div>;
}

// Plain shape — (api, event) => void
const onWheel = (api: publicApiType, ev: React.WheelEvent): void => {
  if (ev.deltaY < 0) api.scrollNext();
  else api.scrollPrev();
};

// Factory shape — (api) => (event) => void
const onMouseDown =
  (_api: publicApiType) =>
  (ev: React.MouseEvent): void => {
    ev.preventDefault(); // block native image/link drag inside items
  };

const ids = ['a', 'b', 'c', 'd', 'e', 'f'];

export function Menu() {
  return (
    <ScrollMenu onWheel={onWheel} onMouseDown={onMouseDown}>
      {ids.map((id) => (
        <Card itemId={id} key={id} />
      ))}
    </ScrollMenu>
  );
}

Core Patterns

Mouse drag-to-scroll (DragDealer)

The complete pattern from the MouseDrag story: track pointer position, flip a dragging flag once movement exceeds 5px, scroll the container by the delta, clear the flag in requestAnimationFrame after mouseup so item onClick (which fires after the drag ends) can still see it and bail, and stop the drag via onMouseLeave so the menu does not keep following a cursor that left it.

tsxCopy code
import React from 'react';
import {
  ScrollMenu,
  VisibilityContext,
  type publicApiType,
} from 'react-horizontal-scrolling-menu';
import 'react-horizontal-scrolling-menu/dist/styles.css';

class DragDealer {
  clicked = false;
  dragging = false;
  position = 0;

  dragStart = (ev: React.MouseEvent) => {
    this.position = ev.clientX;
    this.clicked = true;
  };

  // Clear flags one frame later: item onClick fires after mouseup and must
  // still be able to read `dragging` to skip selection.
  dragStop = () => {
    window.requestAnimationFrame(() => {
      this.dragging = false;
      this.clicked = false;
    });
  };

  dragMove = (ev: React.MouseEvent, cb: (posDiff: number) => void) => {
    const newDiff = this.position - ev.clientX;
    const movedEnough = Math.abs(newDiff) > 5;

    if (this.clicked && movedEnough) {
      this.dragging = true;
    }
    if (this.dragging && movedEnough) {
      this.position = ev.clientX;
      cb(newDiff);
    }
  };
}

function Card({
  itemId,
  onClick,
  selected,
}: {
  itemId: string;
  onClick: () => void;
  selected: boolean;
}) {
  const api = React.useContext<publicApiType>(VisibilityContext);
  const visible = api.useIsVisible(itemId, true);
  return (
    <div
      onClick={onClick}
      role="button"
      tabIndex={0}
      style={{
        width: 160,
        height: 120,
        userSelect: 'none', // no text selection while dragging
        opacity: visible ? 1 : 0.5,
        background: selected ? 'lightgreen' : 'bisque',
      }}
    >
      {itemId}
    </div>
  );
}

const ids = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];

export function MouseDragMenu() {
  const [selected, setSelected] = React.useState<string[]>([]);
  const dragState = React.useRef(new DragDealer());

  const handleDrag =
    ({ scrollContainer }: publicApiType) =>
    (ev: React.MouseEvent) =>
      dragState.current.dragMove(ev, (posDiff) => {
        if (scrollContainer.current) {
          scrollContainer.current.scrollLeft += posDiff;
        }
      });

  const handleItemClick = (itemId: string) => {
    if (dragState.current.dragging) {
      return; // a drag just ended — not a real click
    }
    setSelected((cur) =>
      cur.includes(itemId)
        ? cur.filter((el) => el !== itemId)
        : [...cur, itemId],
    );
  };

  return (
    <ScrollMenu
      onMouseDown={() => dragState.current.dragStart}
      onMouseUp={() => dragState.current.dragStop}
      onMouseMove={handleDrag}
      onMouseLeave={() => dragState.current.dragStop}
    >
      {ids.map((id) => (
        <Card
          itemId={id}
          key={id}
          selected={selected.includes(id)}
          onClick={() => handleItemClick(id)}
        />
      ))}
    </ScrollMenu>
  );
}

On a scroll-snap-type: mandatory rail this drag stutters: the browser snaps every scrollLeft write. Set scrollSnapType = 'none' on the container for the gesture, glide to the closest item with scrollToItem on release, and restore it once scrolling settles — skills/menu-recipes/references/scroll-snap.md.

Touchpad vs mouse-wheel detection

One menu page per wheel tick, while touchpad gestures fall through to native horizontal scrolling. There is no standard way to distinguish the two; the heuristic is that touchpads emit deltaX (or small deltaY), a mouse wheel emits large deltaY only.

tsxCopy code
import React from 'react';
import {
  ScrollMenu,
  type publicApiType,
} from 'react-horizontal-scrolling-menu';
import 'react-horizontal-scrolling-menu/dist/styles.css';

function onWheel(api: publicApiType, ev: React.WheelEvent): void {
  const isTouchpad = Math.abs(ev.deltaX) !== 0 || Math.abs(ev.deltaY) < 15;

  if (isTouchpad) {
    ev.stopPropagation(); // let native scroll handle the gesture
    return;
  }

  if (ev.deltaY < 0) {
    api.scrollNext();
  } else {
    api.scrollPrev();
  }
}

function Item({ itemId }: { itemId: string }) {
  return <div style={{ width: 160, height: 80 }}>{itemId}</div>;
}

const ids = ['a', 'b', 'c', 'd', 'e', 'f'];

export function WheelMenu() {
  return (
    <ScrollMenu onWheel={onWheel}>
      {ids.map((id) => (
        <Item itemId={id} key={id} />
      ))}
    </ScrollMenu>
  );
}

Locking body scroll while over the menu

React attaches wheel listeners as passive, so ev.preventDefault() inside the onWheel prop throws. Lock the page with a non-passive document-level listener toggled on hover instead. ScrollMenu has no onMouseEnter prop, so the toggle lives on a wrapper div.

tsxCopy code
import React from 'react';
import {
  ScrollMenu,
  type publicApiType,
} from 'react-horizontal-scrolling-menu';
import 'react-horizontal-scrolling-menu/dist/styles.css';

function usePreventBodyScroll() {
  const preventDefault = React.useCallback((ev: Event) => {
    ev.preventDefault();
  }, []);

  const enableScroll = React.useCallback(() => {
    document.removeEventListener('wheel', preventDefault, false);
  }, [preventDefault]);

  const disableScroll = React.useCallback(() => {
    document.addEventListener('wheel', preventDefault, { passive: false });
  }, [preventDefault]);

  // re-enable body scroll on unmount
  React.useEffect(() => enableScroll, [enableScroll]);

  return { disableScroll, enableScroll };
}

const onWheel = (api: publicApiType, ev: React.WheelEvent): void => {
  const isTouchpad = Math.abs(ev.deltaX) !== 0 || Math.abs(ev.deltaY) < 15;
  if (isTouchpad) {
    ev.stopPropagation();
    return;
  }
  if (ev.deltaY < 0) api.scrollNext();
  else api.scrollPrev();
};

function Item({ itemId }: { itemId: string }) {
  return <div style={{ width: 160, height: 80 }}>{itemId}</div>;
}

const ids = ['a', 'b', 'c', 'd', 'e', 'f'];

export function LockedMenu() {
  const { disableScroll, enableScroll } = usePreventBodyScroll();

  return (
    <div onMouseEnter={disableScroll} onMouseLeave={enableScroll}>
      <ScrollMenu onWheel={onWheel}>
        {ids.map((id) => (
          <Item itemId={id} key={id} />
        ))}
      </ScrollMenu>
    </div>
  );
}

Common Mistakes

CRITICAL Plain handler passed where factory expected

Wrong:

tsxCopy code
<ScrollMenu onMouseMove={(ev) => drag(ev)}>

Correct:

tsxCopy code
<ScrollMenu onMouseMove={(api) => (ev) => drag(ev)}>

onWheel/onScroll are plain (api, event) => void, but ALL mouse/touch props are factories (api) => (event) => void — ScrollMenu calls the prop with the api during render, so a plain handler receives the api object as its "event", runs once per render, and its return value is attached as the DOM handler, which silently does nothing useful.

Source: src/index.tsx:101-107,322-328; README.md props table note

HIGH Drag-to-scroll fires item clicks on release

Wrong:

tsxCopy code
<Card onClick={() => select(id)} /> /* fires after every drag */

Correct:

tsxCopy code
<Card
  onClick={() => {
    if (!dragState.current.dragging) select(id);
  }}
/>
// dragging is cleared inside requestAnimationFrame after mouseUp,
// so it is still true when the post-drag click fires (DragDealer.dragStop)

After a drag ends the browser still dispatches a click on the item under the cursor; guard click handlers with a dragging flag that is cleared one animation frame after mouseup.

Source: stories/MouseDrag/MouseDrag.source.tsx (DragDealer class)

HIGH Drag keeps scrolling after cursor leaves

Wrong:

tsxCopy code
<ScrollMenu
  onMouseDown={() => dragState.current.dragStart}
  onMouseUp={() => dragState.current.dragStop}
  onMouseMove={handleDrag}
>

Correct:

tsxCopy code
<ScrollMenu
  onMouseDown={() => dragState.current.dragStart}
  onMouseUp={() => dragState.current.dragStop}
  onMouseMove={handleDrag}
  onMouseLeave={() => dragState.current.dragStop}
>

Without wiring onMouseLeave to end the drag, the container keeps following a mouse that is no longer over it (mouseup outside the menu is never seen).

Source: https://github.com/asmyshlyaev177/react-horizontal-scrolling-menu/issues/278 (v7.1.0)

MEDIUM preventDefault in passive wheel/touchmove listeners

Wrong:

tsxCopy code
onWheel={(api, ev) => { ev.preventDefault(); api.scrollNext(); }}

Correct:

tsxCopy code
onWheel={(api, ev) => {
  const isTouchpad = Math.abs(ev.deltaX) !== 0 || Math.abs(ev.deltaY) < 15;
  if (isTouchpad) return; // let native scroll handle it
  ev.deltaY < 0 ? api.scrollPrev() : api.scrollNext();
}}

React 17+ attaches wheel/touchmove as passive listeners, so ev.preventDefault() throws "Unable to preventDefault inside passive event listener" — body-scroll locking needs the non-passive workaround (the document-level listener pattern above, or CSS overscroll-behavior).

Source: stories/PreventBodyScroll/PreventBodyScroll.source.tsx; stories/Simple onWheel recipe

MEDIUM Reading positions in onScroll mid-animation

Wrong:

tsxCopy code
onScroll={(api) => savePosition(api.scrollContainer.current.scrollLeft)}

Correct:

tsxCopy code
onUpdate={(api) => savePosition(api.scrollContainer.current?.scrollLeft ?? 0)}

onScroll fires before the scroll settles (documented in the props table), so position reads there are intermediate mid-animation values — save state from onUpdate or poll after the transition finishes.

Source: README.md props table (onScroll fires before scroll settles); stories/SaveRestorePosition

See also

• ../menu-recipes/SKILL.md — drag, wheel and body-scroll recipes compose these pointer callback shapes into features (autoplay, one item per scroll, save/restore position).