From 00b53d2f7f93c3a4926cc619681578809f4a52f3 Mon Sep 17 00:00:00 2001
From: Peter Abbondanzo <abbo@meta.com>
Date: Thu, 24 Sep 2026 13:41:50 -0700
Subject: [PATCH] Fire VirtualizedList edge callbacks after programmatic
 scrolling

Summary:
Programmatic list scrolling can move to an edge before asynchronously scheduled cells finish rendering. The scroll handler then skips the edge callback because the terminal cell is not yet in the render window, and no later scroll or layout event is guaranteed.

Recheck edge callbacks after post-scroll render updates. Track the item count when an edge callback is sent so internal measurement changes cannot emit duplicates while the list remains at the same edge; appending data or scrolling away re-arms the callback.

Changelog:
[General][Fixed] - Fire `VirtualizedList` edge callbacks after programmatic scrolling

Differential Revision: D100870075
---
 .../examples/FlatList/BaseFlatListExample.js  |   3 +-
 .../FlatList/FlatList-onEndReached.js         | 126 +++++++++--
 .../Lists/VirtualizedList.js                  |  68 ++++--
 .../Lists/__tests__/VirtualizedList-test.js   | 198 ++++++++++++++++++
 4 files changed, 357 insertions(+), 38 deletions(-)

diff --git a/packages/rn-tester/js/examples/FlatList/BaseFlatListExample.js b/packages/rn-tester/js/examples/FlatList/BaseFlatListExample.js
index 1c77581facfd..ff6b3fb27798 100644
--- a/packages/rn-tester/js/examples/FlatList/BaseFlatListExample.js
+++ b/packages/rn-tester/js/examples/FlatList/BaseFlatListExample.js
@@ -60,6 +60,7 @@ const Item = ({item, separators}: ListRenderItemInfo<string>) => {
 };
 
 type Props = Readonly<{
+  data?: ReadonlyArray<string>,
   exampleProps: Partial<React.ElementConfig<typeof FlatList>>,
   exampleTestID?: ?string,
   onTest?: ?() => void,
@@ -95,7 +96,7 @@ const BaseFlatListExample: component(
         ref={ref}
         testID="flat_list"
         // $FlowFixMe[incompatible-type]
-        data={DATA}
+        data={props.data ?? DATA}
         keyExtractor={(item, index) => item + index}
         style={styles.list}
         // $FlowFixMe[incompatible-type]
diff --git a/packages/rn-tester/js/examples/FlatList/FlatList-onEndReached.js b/packages/rn-tester/js/examples/FlatList/FlatList-onEndReached.js
index 132778d07b87..2a60d653160f 100644
--- a/packages/rn-tester/js/examples/FlatList/FlatList-onEndReached.js
+++ b/packages/rn-tester/js/examples/FlatList/FlatList-onEndReached.js
@@ -12,33 +12,129 @@
 
 import type {RNTesterModuleExample} from '../../types/RNTesterTypes';
 
-import BaseFlatListExample from './BaseFlatListExample';
+import BaseFlatListExample, {ITEM_HEIGHT} from './BaseFlatListExample';
 import * as React from 'react';
 import {useRef, useState} from 'react';
+import {Button, FlatList} from 'react-native';
+
+const DATA = Array.from({length: 20}, (_, index) => `Item ${index}`);
+const SCROLL_TO_ITEM = DATA[18];
+
+type EventCounts = {
+  dragEvents: number,
+  onEndReached: number,
+  onMomentumScrollEnd: number,
+  onStartReached: number,
+};
 
 export component FlatList_onEndReached() {
-  const [output, setOutput] = useState('');
-  const exampleProps = {
-    onEndReached: (info: {distanceFromEnd: number, ...}) =>
-      setOutput('onEndReached'),
-    onEndReachedThreshold: 0,
+  const [output, setOutput] = useState('ready');
+  const listRef = useRef<?FlatList<string>>(null);
+  const actionRef = useRef<'end' | 'start'>('end');
+  const attemptsRef = useRef(0);
+  const eventCountsRef = useRef<EventCounts>({
+    dragEvents: 0,
+    onEndReached: 0,
+    onMomentumScrollEnd: 0,
+    onStartReached: 0,
+  });
+  const recordEventsRef = useRef(false);
+  const momentumEndedRef = useRef(false);
+
+  const report = () => {
+    const {dragEvents, onEndReached, onMomentumScrollEnd, onStartReached} =
+      eventCountsRef.current;
+    setOutput(
+      `${actionRef.current}: attempts=${attemptsRef.current}, ` +
+        `onEndReached=${onEndReached}, onStartReached=${onStartReached}, ` +
+        `onMomentumScrollEnd=${onMomentumScrollEnd}, dragEvents=${dragEvents}`,
+    );
+  };
+
+  const onEndReached = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.onEndReached++;
+      if (momentumEndedRef.current) {
+        report();
+      }
+    }
+  };
+
+  const onStartReached = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.onStartReached++;
+      if (momentumEndedRef.current) {
+        report();
+      }
+    }
   };
-  const ref = useRef<any>(null);
 
-  const onTest = () => {
-    const scrollResponder = ref?.current?.getScrollResponder();
-    if (scrollResponder != null) {
-      scrollResponder.scrollToEnd();
+  const onMomentumScrollEnd = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.onMomentumScrollEnd++;
+      momentumEndedRef.current = true;
+      report();
     }
   };
 
+  const onDragEvent = () => {
+    if (recordEventsRef.current) {
+      eventCountsRef.current.dragEvents++;
+    }
+  };
+
+  const scrollToEnd = () => {
+    recordEventsRef.current = true;
+    momentumEndedRef.current = false;
+    actionRef.current = 'end';
+    attemptsRef.current++;
+    setOutput('running');
+    listRef.current?.scrollToItem({
+      animated: true,
+      item: SCROLL_TO_ITEM,
+      viewOffset: -ITEM_HEIGHT,
+    });
+  };
+
+  const scrollToStart = () => {
+    momentumEndedRef.current = false;
+    actionRef.current = 'start';
+    attemptsRef.current++;
+    setOutput('running');
+    listRef.current?.scrollToOffset({animated: true, offset: 0});
+  };
+
+  const exampleProps = {
+    initialNumToRender: 19,
+    onEndReached,
+    onEndReachedThreshold: 0.2,
+    onMomentumScrollEnd,
+    onScrollBeginDrag: onDragEvent,
+    onScrollEndDrag: onDragEvent,
+    onStartReached,
+    onStartReachedThreshold: 0.1,
+    windowSize: 2,
+  };
+
   return (
     <BaseFlatListExample
-      ref={ref}
+      ref={listRef}
+      data={DATA}
       exampleProps={exampleProps}
       testOutput={output}
-      onTest={onTest}
-    />
+      onTest={scrollToEnd}
+      testLabel="Scroll to item">
+      <Button
+        testID="scroll_to_start"
+        onPress={scrollToStart}
+        title="Scroll to start"
+      />
+      <Button
+        testID="scroll_to_end"
+        onPress={scrollToEnd}
+        title="Scroll to item"
+      />
+    </BaseFlatListExample>
   );
 }
 
@@ -46,7 +142,7 @@ export default {
   title: 'onEndReached',
   name: 'onEndReached',
   description:
-    'Scroll to end of list or tap Test button to see `onEndReached` triggered.',
+    'Programmatic scrolling calls edge callbacks once and does not emit drag callbacks.',
   render: function () {
     return <FlatList_onEndReached />;
   },
diff --git a/packages/virtualized-lists/Lists/VirtualizedList.js b/packages/virtualized-lists/Lists/VirtualizedList.js
index 601419b1e804..6805627b77e4 100644
--- a/packages/virtualized-lists/Lists/VirtualizedList.js
+++ b/packages/virtualized-lists/Lists/VirtualizedList.js
@@ -1195,7 +1195,7 @@ class VirtualizedList extends StateSafePureComponent<
   }
 
   componentDidUpdate(prevProps: VirtualizedListProps) {
-    const {data, extraData, getItemLayout} = this.props;
+    const {data, extraData} = this.props;
     if (data !== prevProps.data || extraData !== prevProps.extraData) {
       // clear the viewableIndices cache to also trigger
       // the onViewableItemsChanged callback with the new data
@@ -1217,11 +1217,14 @@ class VirtualizedList extends StateSafePureComponent<
       this._hiPriInProgress = false;
     }
 
-    // We only call `onEndReached` after we render the last cell, but when
-    // getItemLayout is present, we can scroll past the last rendered cell, and
-    // never trigger a new layout or bounds change, so we need to check again
-    // after rendering more cells.
-    if (getItemLayout != null) {
+    // We only call `onEndReached` after we render the last cell, but
+    // programmatic scrolling (e.g. scrollToItem, scrollToIndex) or using
+    // getItemLayout can scroll past the last rendered cell, and never
+    // trigger a new layout or bounds change, so we need to check again
+    // after rendering more cells. We gate on having received at least one
+    // scroll event (timestamp > 0) to avoid false onEndReached calls
+    // during initial render.
+    if (this.props.getItemLayout != null || this._scrollMetrics.timestamp > 0) {
       this._maybeCallOnEdgeReached();
     }
   }
@@ -1264,8 +1267,10 @@ class VirtualizedList extends StateSafePureComponent<
     zoomScale: 1,
   };
   _scrollRef: ?React.ElementRef<typeof ScrollView> = null;
-  _sentStartForContentLength = 0;
-  _sentEndForContentLength = 0;
+  _sentStartForItemCount: ?number = null;
+  _sentStartForOffset: ?number = null;
+  _sentEndForItemCount: ?number = null;
+  _sentEndForOffset: ?number = null;
   _updateCellsToRenderTimeoutID: ?ReturnType<typeof setTimeout> = null;
   _viewabilityTuples: Array<ViewabilityHelperCallbackTuple> = [];
 
@@ -1557,7 +1562,7 @@ class VirtualizedList extends StateSafePureComponent<
     };
   }
 
-  _maybeCallOnEdgeReached() {
+  _maybeCallOnEdgeReached(isScrollEvent: boolean = false) {
     const {
       data,
       getItemCount,
@@ -1610,39 +1615,53 @@ class VirtualizedList extends StateSafePureComponent<
     const isWithinStartThreshold = distanceFromStart <= startThreshold;
     const isWithinEndThreshold = distanceFromEnd <= endThreshold;
 
+    const itemCount = getItemCount(data);
+
     // First check if the user just scrolled within the end threshold
-    // and call onEndReached only once for a given content length,
+    // and call onEndReached only once for a given item count,
     // and only if onStartReached is not being executed
     if (
       onEndReached &&
-      this.state.cellsAroundViewport.last === getItemCount(data) - 1 &&
+      this.state.cellsAroundViewport.last === itemCount - 1 &&
       isWithinEndThreshold &&
-      this._listMetrics.getContentLength() !== this._sentEndForContentLength
+      itemCount !== this._sentEndForItemCount
     ) {
-      this._sentEndForContentLength = this._listMetrics.getContentLength();
+      this._sentEndForItemCount = itemCount;
+      this._sentEndForOffset = offset;
       onEndReached({distanceFromEnd});
     }
 
     // Next check if the user just scrolled within the start threshold
-    // and call onStartReached only once for a given content length,
+    // and call onStartReached only once for a given item count,
     // and only if onEndReached is not being executed
     if (
       onStartReached != null &&
       this.state.cellsAroundViewport.first === 0 &&
       isWithinStartThreshold &&
-      this._listMetrics.getContentLength() !== this._sentStartForContentLength
+      itemCount !== this._sentStartForItemCount
     ) {
-      this._sentStartForContentLength = this._listMetrics.getContentLength();
+      this._sentStartForItemCount = itemCount;
+      this._sentStartForOffset = offset;
       onStartReached({distanceFromStart});
     }
 
     // If the user scrolls away from the start or end and back again,
     // cause onStartReached or onEndReached to be triggered again
-    if (!isWithinStartThreshold) {
-      this._sentStartForContentLength = 0;
+    if (isScrollEvent && this._sentStartForOffset != null) {
+      if (offset < this._sentStartForOffset) {
+        this._sentStartForOffset = offset;
+      } else if (!isWithinStartThreshold && offset > this._sentStartForOffset) {
+        this._sentStartForItemCount = null;
+        this._sentStartForOffset = null;
+      }
     }
-    if (!isWithinEndThreshold) {
-      this._sentEndForContentLength = 0;
+    if (isScrollEvent && this._sentEndForOffset != null) {
+      if (offset > this._sentEndForOffset) {
+        this._sentEndForOffset = offset;
+      } else if (!isWithinEndThreshold && offset < this._sentEndForOffset) {
+        this._sentEndForItemCount = null;
+        this._sentEndForOffset = null;
+      }
     }
   }
 
@@ -1784,13 +1803,18 @@ class VirtualizedList extends StateSafePureComponent<
       zoomScale,
     };
     if (this.state.pendingScrollUpdateCount > 0) {
-      this.setState<'pendingScrollUpdateCount'>({pendingScrollUpdateCount: 0});
+      this.setState<'pendingScrollUpdateCount'>(
+        {pendingScrollUpdateCount: 0},
+        () => {
+          this._maybeCallOnEdgeReached(true);
+        },
+      );
     }
     this._updateViewableItems(this.props, this.state.cellsAroundViewport);
     if (!this.props) {
       return;
     }
-    this._maybeCallOnEdgeReached();
+    this._maybeCallOnEdgeReached(true);
     if (velocity !== 0) {
       this._fillRateHelper.activate();
     }
diff --git a/packages/virtualized-lists/Lists/__tests__/VirtualizedList-test.js b/packages/virtualized-lists/Lists/__tests__/VirtualizedList-test.js
index e270af4649c9..b9a697bd92bd 100644
--- a/packages/virtualized-lists/Lists/__tests__/VirtualizedList-test.js
+++ b/packages/virtualized-lists/Lists/__tests__/VirtualizedList-test.js
@@ -799,6 +799,204 @@ describe('VirtualizedList', () => {
     expect(onEndReached).toHaveBeenCalled();
   });
 
+  it('deduplicates edge callbacks and re-arms after data or scroll changes', async () => {
+    const ITEM_HEIGHT = 40;
+    const layout = {width: 300, height: 600};
+    let data = Array(40)
+      .fill()
+      .map((_, index) => ({key: `key-${index}`}));
+    const onEndReached = jest.fn();
+    const onStartReached = jest.fn();
+    const props = {
+      data,
+      initialNumToRender: 10,
+      onEndReachedThreshold: 1,
+      onStartReachedThreshold: 1,
+      windowSize: 2,
+      renderItem: ({item}) => <item value={item.key} />,
+      getItem: (items, index) => items[index],
+      getItemCount: items => items.length,
+      onEndReached,
+      onStartReached,
+    };
+
+    let component;
+    await act(() => {
+      component = create(<VirtualizedList {...props} />);
+    });
+    const instance = component.getInstance();
+
+    await act(() => {
+      instance._onLayout({nativeEvent: {layout, zoomScale: 1}});
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT);
+      for (let i = 0; i < props.initialNumToRender; i++) {
+        simulateCellLayout(component, data, i, {
+          width: layout.width,
+          height: ITEM_HEIGHT,
+          x: 0,
+          y: i * ITEM_HEIGHT,
+        });
+      }
+      performAllBatches();
+    });
+    expect(onEndReached).not.toHaveBeenCalled();
+    expect(onStartReached).toHaveBeenCalledTimes(1);
+
+    const scrollToEnd = async (
+      timeStamp: number,
+      sendSettledEvent: boolean = false,
+    ) => {
+      await act(() => {
+        const nativeEvent = {
+          contentOffset: {
+            y: data.length * ITEM_HEIGHT - layout.height,
+            x: 0,
+          },
+          layoutMeasurement: layout,
+          contentSize: {...layout, height: data.length * ITEM_HEIGHT},
+          zoomScale: 1,
+          contentInset: {right: 0, top: 0, left: 0, bottom: 0},
+        };
+        instance._onScroll({timeStamp, nativeEvent});
+        if (sendSettledEvent) {
+          instance._onScroll({timeStamp: timeStamp + 1, nativeEvent});
+        }
+        performAllBatches();
+      });
+    };
+
+    const scrollToStart = async (
+      timeStamp: number,
+      sendSettledEvent: boolean = false,
+    ) => {
+      await act(() => {
+        const nativeEvent = {
+          contentOffset: {y: 0, x: 0},
+          layoutMeasurement: layout,
+          contentSize: {...layout, height: data.length * ITEM_HEIGHT},
+          zoomScale: 1,
+          contentInset: {right: 0, top: 0, left: 0, bottom: 0},
+        };
+        instance._onScroll({timeStamp, nativeEvent});
+        if (sendSettledEvent) {
+          instance._onScroll({timeStamp: timeStamp + 1, nativeEvent});
+        }
+        performAllBatches();
+      });
+    };
+
+    await scrollToEnd(1000);
+    expect(onEndReached).toHaveBeenCalledTimes(1);
+    expect(onEndReached).toHaveBeenLastCalledWith({distanceFromEnd: 0});
+
+    await act(() => {
+      instance.setState({pendingScrollUpdateCount: 1});
+    });
+    await scrollToStart(2000);
+    expect(onStartReached).toHaveBeenCalledTimes(2);
+    await scrollToStart(2100, true);
+    expect(onStartReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance.setState({pendingScrollUpdateCount: 1});
+    });
+    await scrollToEnd(3000);
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+    await scrollToEnd(3100, true);
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    const endOffset = data.length * ITEM_HEIGHT - layout.height;
+    const deepestEndOffset = endOffset + 100;
+    const expandedContentHeight =
+      data.length * ITEM_HEIGHT + layout.height * 2 + 1;
+
+    await act(() => {
+      instance._onScroll({
+        timeStamp: 3200,
+        nativeEvent: {
+          contentOffset: {y: deepestEndOffset, x: 0},
+          layoutMeasurement: layout,
+          contentSize: {...layout, height: data.length * ITEM_HEIGHT},
+          zoomScale: 1,
+          contentInset: {right: 0, top: 0, left: 0, bottom: 0},
+        },
+      });
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance._onContentSizeChange(300, expandedContentHeight);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance._onScroll({
+        timeStamp: 3500,
+        nativeEvent: {
+          contentOffset: {y: deepestEndOffset, x: 0},
+          layoutMeasurement: layout,
+          contentSize: {...layout, height: expandedContentHeight},
+          zoomScale: 1,
+          contentInset: {right: 0, top: 0, left: 0, bottom: 0},
+        },
+      });
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance._onContentSizeChange(300, expandedContentHeight);
+      instance._onScroll({
+        timeStamp: 3600,
+        nativeEvent: {
+          contentOffset: {y: deepestEndOffset - 50, x: 0},
+          layoutMeasurement: layout,
+          contentSize: {...layout, height: expandedContentHeight},
+          zoomScale: 1,
+          contentInset: {right: 0, top: 0, left: 0, bottom: 0},
+        },
+      });
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(2);
+
+    await act(() => {
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(3);
+
+    data = [...data, {key: `key-${data.length}`}];
+    await act(() => {
+      component.update(<VirtualizedList {...props} data={data} />);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(4);
+
+    await act(() => {
+      instance._onContentSizeChange(300, data.length * ITEM_HEIGHT);
+      performAllBatches();
+    });
+    expect(onEndReached).toHaveBeenCalledTimes(4);
+
+    await scrollToEnd(4000);
+    expect(onEndReached).toHaveBeenCalledTimes(4);
+
+    await scrollToStart(5000);
+    expect(onStartReached).toHaveBeenCalledTimes(3);
+
+    await scrollToEnd(6000);
+    expect(onEndReached).toHaveBeenCalledTimes(5);
+  });
+
   it('does not call onEndReached when onContentSizeChange happens after onLayout', async () => {
     const ITEM_HEIGHT = 40;
     const layout = {width: 300, height: 600};