[Web] Activate ScrollView's native gesture on real scroll instead of pointer distance

[m-bert]

Description

On web, NativeViewGestureHandler activated after ~15px of pointer movement in any direction, even though the browser does the scrolling itself. A vertical ScrollView would claim horizontal drags, and once active, InteractionManager failed any Pan whose activation criteria (minDistance, activeOffsetX, ...) delayed activation past the slop - such pans could never activate inside a ScrollView or FlatList.

This PR adds ScrollEventManager which delivers the view's scroll events to handlers via a new onScroll hook. Handlers with the ScrollView role now activate only when the view actually scrolls, with a 2px pointer travel requirement that ignores momentum-scroll ticks after a touch meant to stop a fling.

Important

This covers only new, hook based API

Test plan

• Unit tests for scroll-driven activation, the momentum guard and the unchanged legacy path
• Pan activation criteria screen: all boxes activate per their criteria inside the ScrollView, negatives stay inactive, scrolling works
• Buttons in FlatList screen: scrolling from a button doesn't fire a press, taps do; tap-to-stop-momentum fires nothing and the next tap works

Tested on the following code:

import React, { useRef, useState } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import {
  GestureDetector,
  ScrollView,
  usePanGesture,
} from 'react-native-gesture-handler';
import Animated, {
  interpolateColor,
  useAnimatedStyle,
  useSharedValue,
  withTiming,
} from 'react-native-reanimated';

import type { FeedbackHandle } from '../../../common';
import { COLORS, commonStyles, Feedback } from '../../../common';

type PanConfig = Parameters<typeof usePanGesture>[0];

type DraggableBoxProps = {
  label: string;
  comment: string;
  config?: PanConfig;
  onActivated: (label: string) => void;
};

function DraggableBox({ label, comment, config, onActivated }: DraggableBoxProps) {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const colorProgress = useSharedValue(0);

  const panGesture = usePanGesture({
    minDistance: config?.minDistance,
    minVelocity: config?.minVelocity,
    activeOffsetX: config?.activeOffsetX,
    maxPointers: config?.maxPointers,
    runOnJS: true,
    onActivate: () => {
      colorProgress.value = withTiming(1, { duration: 100 });
      onActivated(label);
    },
    onUpdate: (event) => {
      translateX.value = event.translationX;
      translateY.value = event.translationY;
    },
    onFinalize: () => {
      colorProgress.value = withTiming(0, { duration: 100 });
      translateX.value = withTiming(0);
      translateY.value = withTiming(0);
    },
  });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [
      { translateX: translateX.value },
      { translateY: translateY.value },
    ],
    backgroundColor: interpolateColor(
      colorProgress.value,
      [0, 1],
      [COLORS.NAVY, COLORS.GREEN]
    ),
  }));

  return (
    <View style={[commonStyles.subcontainer, styles.entry]}>
      <GestureDetector gesture={panGesture}>
        <Animated.View style={[styles.box, animatedStyle]}>
          <Text style={styles.label}>{label}</Text>
        </Animated.View>
      </GestureDetector>
      <Text style={commonStyles.instructions}>{comment}</Text>
    </View>
  );
}

export default function PanActivationCriteriaExample() {
  const [maxPointers, setMaxPointers] = useState(1);
  const feedbackRef = useRef<FeedbackHandle>(null);

  const onActivated = (label: string) =>
    feedbackRef.current?.showMessage(`Activated: ${label}`);

  return (
    <View style={styles.container}>
      <ScrollView style={styles.scroll}>
        <Text style={commonStyles.instructions}>
          Each box turns green the moment its pan activates. Drag each one and
          verify the activation criteria are respected.
        </Text>
        <DraggableBox
          label="minDistance: 100"
          comment="Should activate only after the finger travels 100pt in any direction."
          config={{ minDistance: 100 }}
          onActivated={onActivated}
        />
        <DraggableBox
          label="minVelocity: 800"
          comment="Should activate only on a fast drag (over 800pt/s), regardless of direction. Slow drags must never activate."
          config={{ minVelocity: 800 }}
          onActivated={onActivated}
        />
        <DraggableBox
          label="activeOffsetX: ±60"
          comment="Should activate only after moving 60pt horizontally. Vertical drags must not activate."
          config={{ activeOffsetX: [-60, 60] }}
          onActivated={onActivated}
        />
        <View style={styles.updateSection}>
          <DraggableBox
            label={`minDistance: 120\nmaxPointers: ${maxPointers}`}
            comment="Explicit minDistance combined with another prop updated at runtime. After pressing the button below, activation must still require 120pt of travel — partial config updates must not reset minDistance."
            config={{ minDistance: 120, maxPointers }}
            onActivated={onActivated}
          />
          <Button
            title="Update unrelated prop (maxPointers)"
            onPress={() => setMaxPointers((prev) => (prev === 1 ? 2 : 1))}
          />
        </View>
      </ScrollView>
      <View style={styles.feedbackOverlay} pointerEvents="none">
        <Feedback ref={feedbackRef} duration={2000} />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  scroll: {
    paddingVertical: 24,
  },
  feedbackOverlay: {
    position: 'absolute',
    bottom: 20,
    alignSelf: 'center',
  },
  entry: {
    paddingVertical: 24,
    gap: 12,
  },
  box: {
    width: 150,
    height: 150,
    borderRadius: 20,
    justifyContent: 'center',
    alignItems: 'center',
  },
  label: {
    color: 'white',
    fontWeight: '600',
    textAlign: 'center',
  },
  updateSection: {
    paddingBottom: 32,
  },
});

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 480eede6-0666-4d22-ba20-1b7a85ac09d7

📥 Commits

Reviewing files that changed from the base of the PR and between 648473f and 77fa382.

📒 Files selected for processing (1)

• packages/react-native-gesture-handler/src/web/handlers/NativeViewGestureHandler.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/react-native-gesture-handler/src/web/handlers/NativeViewGestureHandler.ts

Included review availability: Your plan includes up to 8 reviews per rolling hour; 4 remain after this review.

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Improved web native gesture handling for scrollable views.
  • Scroll gestures now activate based on actual scrolling and pointer movement.
  • Preserved distance-based activation for non-scrollable views.

• Bug Fixes

  • Prevented pointer movement alone from incorrectly activating scroll-driven gestures.
  • Improved handling of momentum stops and untracked scrolling.

• Tests

  • Added coverage for scroll activation, pointer movement, momentum behavior, and non-scrollable views.

Walkthrough

Web native view gestures now receive scroll events. Scrollable handlers activate only after scrolling and pointer travel. Non-scrollable and role-less handlers retain distance-based activation. Tests cover the new behavior with a fake DOM.

Changes

Web scroll activation

Layer / File(s)	Summary
Scroll event pipeline packages/react-native-gesture-handler/src/web/tools/EventManager.ts, packages/react-native-gesture-handler/src/web/tools/ScrollEventManager.ts, packages/react-native-gesture-handler/src/web/tools/GestureHandlerWebDelegate.ts, packages/react-native-gesture-handler/src/web/handlers/GestureHandler.ts	The web delegate registers passive scroll listeners. ScrollEventManager maps scroll offsets to adapted move events and forwards them through the gesture handler callback.
Native view scroll activation packages/react-native-gesture-handler/src/web/handlers/NativeViewGestureHandler.ts	Native view handlers detect scroll roles, track scroll state, require pointer travel after scrolling, preserve distance activation for other views, and reset scroll state.
Activation behavior tests packages/react-native-gesture-handler/src/__tests__/webNativeViewGestureHandler.test.ts	A fake DOM and test utilities validate scroll activation, momentum-stop behavior, untracked scroll events, and distance activation for non-scrollable and role-less views.

Sequence Diagram(s)

sequenceDiagram
  participant Pointer
  participant GestureHandlerWebDelegate
  participant ScrollEventManager
  participant NativeViewGestureHandler
  Pointer->>NativeViewGestureHandler: begin touch
  GestureHandlerWebDelegate->>ScrollEventManager: register scroll listener
  ScrollEventManager->>NativeViewGestureHandler: forward adapted scroll event
  Pointer->>NativeViewGestureHandler: move pointer
  NativeViewGestureHandler->>NativeViewGestureHandler: activate after scroll and travel threshold

Loading

Merge Risk: ⚪ Minimal · up to 77fa3

This PR changes web ScrollView gesture activation to follow actual scrolling, preventing scroll gestures from incorrectly claiming unrelated drags. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: activating the web NativeViewGestureHandler on real scrolling instead of pointer distance.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR updates the web implementation of NativeViewGestureHandler (v3 / hook-based API path) so ScrollView-role handlers activate based on actual DOM scroll events rather than pointer-distance slop, preventing scroll views from incorrectly claiming cross-axis drags and blocking delayed-activation pans inside scrollable containers.

Changes:

• Add ScrollEventManager and plumb a new onScroll callback through EventManager → GestureHandler.
• Update NativeViewGestureHandler to use scroll-driven activation for the ScrollView role with a small pointer-travel momentum guard.
• Add Jest unit tests validating scroll-driven activation behavior and ensuring legacy/distance-based activation remains unchanged.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/react-native-gesture-handler/src/web/tools/ScrollEventManager.ts	New event manager that listens to DOM scroll and forwards it into the gesture pipeline.
packages/react-native-gesture-handler/src/web/tools/GestureHandlerWebDelegate.ts	Registers ScrollEventManager alongside existing web event managers.
packages/react-native-gesture-handler/src/web/tools/EventManager.ts	Adds onScroll callback plumbing to the shared event-manager abstraction.
packages/react-native-gesture-handler/src/web/handlers/GestureHandler.ts	Wires onScroll into handler attachment and provides a default no-op implementation.
packages/react-native-gesture-handler/src/web/handlers/NativeViewGestureHandler.ts	Switches ScrollView-role activation to be scroll-driven (v3-only role path).
packages/react-native-gesture-handler/src/tests/webNativeViewGestureHandler.test.ts	New unit tests for scroll-driven activation, momentum guard behavior, and legacy path.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[j-piasecki]

Doesn't the DOM event contain the layout info by chance?

[m-bert]

Unfortunately, scroll event is a generic event, so it doesn't have this info (source)

[j-piasecki]

Why recalculate this on every pointer down? It doesn't change until the gesture is reattached to a different view.

[m-bert]

Set ScrollDriven once

[j-piasecki]

Won't the browser dispatch pointercancel around that time, since it's taking over? That would mean the gesture gets canceled, no?

[m-bert]

It does - pointercancel maps to cancel(), and the scroll events that follow are ignored since the tracker is empty. That's the same outcome as before this PR (the browser takes over below the 15px slop). However, the spec doesn't define the ordering between pointercancel and scroll, so the handler must also handle scroll arriving while the pointer is still tracked - that's the case this test covers.