fix(MessageList): prevent message pagination too early on mount (#3143)

MartinCupela · web-flow · commit 12e282f36706 · 2026-04-28T17:08:58.000+02:00
diff --git a/examples/vite/index.html b/examples/vite/index.html
@@ -5,6 +5,11 @@
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Stream Chat React</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="preload" as="style" href="https://fonts.googleapis.com/css2?family=Geist:wght@100..900&display=swap" />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@100..900&display=swap" />
+    <link rel="preload" as="font" type="font/woff2" crossorigin href="https://fonts.gstatic.com/s/geist/v4/gyByhwUxId8gMEwcGFU.woff2" />
   </head>
   <body>
     <div id="root"></div>
diff --git a/examples/vite/src/index.scss b/examples/vite/src/index.scss
@@ -1,6 +1,7 @@
 @layer stream-new, stream-new-plugins, stream-overrides, stream-app-overrides;
 
-@import url('https://fonts.googleapis.com/css2?family=Geist:wght@100..900&display=swap');
+// Geist font is preloaded in index.html to avoid layout shift on mount.
+//@import url('https://fonts.googleapis.com/css2?family=Geist:wght@100..900&display=swap');
 
 // v3 CSS import
 @import url('stream-chat-react/dist/css/index.css') layer(stream-new);
diff --git a/src/components/InfiniteScrollPaginator/InfiniteScroll.tsx b/src/components/InfiniteScrollPaginator/InfiniteScroll.tsx
@@ -109,9 +109,18 @@ export const InfiniteScroll = (props: PropsWithChildren<InfiniteScrollProps>) =>
 
     scrollElement.addEventListener('scroll', scrollListener, useCapture);
     scrollElement.addEventListener('resize', scrollListener, useCapture);
-    scrollListener();
+
+    // Defer the initial proximity check so that any pending scroll-to-bottom
+    // from useLayoutEffect (e.g. the MessageList settle pass) has been applied
+    // to the DOM before we evaluate whether more pages should be loaded.
+    // Without this, scrollTop is still 0 on mount which falsely triggers
+    // loadPreviousPage and breaks the initial scroll position.
+    const rafId = requestAnimationFrame(() => {
+      scrollListener();
+    });
 
     return () => {
+      cancelAnimationFrame(rafId);
       scrollElement.removeEventListener('scroll', scrollListener, useCapture);
       scrollElement.removeEventListener('resize', scrollListener, useCapture);
     };
diff --git a/src/components/InfiniteScrollPaginator/__tests__/InfiniteScroll.test.tsx b/src/components/InfiniteScrollPaginator/__tests__/InfiniteScroll.test.tsx
@@ -90,6 +90,25 @@ describe('InfiniteScroll', () => {
     },
   );
 
+  it('should not call loadPreviousPage synchronously on mount', () => {
+    renderComponent({
+      hasPreviousPage: true,
+    });
+
+    expect(loadPreviousPage).not.toHaveBeenCalled();
+  });
+
+  it('should defer the initial scroll check to a requestAnimationFrame', () => {
+    const rafSpy = vi.spyOn(window, 'requestAnimationFrame');
+
+    renderComponent({
+      hasPreviousPage: true,
+    });
+
+    expect(rafSpy).toHaveBeenCalledWith(expect.any(Function));
+    rafSpy.mockRestore();
+  });
+
   describe('Rendering loader', () => {
     const getRenderResult = () => {
       const props = fromPartial<InfiniteScrollProps>({
diff --git a/src/components/MessageList/hooks/MessageList/useMessageListScrollManager.ts b/src/components/MessageList/hooks/MessageList/useMessageListScrollManager.ts
@@ -6,6 +6,7 @@ import type { LocalMessage } from 'stream-chat';
 export type ContainerMeasures = {
   offsetHeight: number;
   scrollHeight: number;
+  scrollTop: number;
 };
 
 export type UseMessageListScrollManagerParams = {
@@ -101,6 +102,7 @@ export function useMessageListScrollManager(params: UseMessageListScrollManagerP
   const measures = useRef<ContainerMeasures>({
     offsetHeight: 0,
     scrollHeight: 0,
+    scrollTop: 0,
   });
   const messages = useRef<LocalMessage[]>(undefined);
   const olderPaginationState = useRef<OlderPaginationState>({
@@ -130,16 +132,32 @@ export function useMessageListScrollManager(params: UseMessageListScrollManagerP
     const finishedLoadingOlder = !loadingMore && previousLoadingMoreRef.current;
 
     if (startedLoadingOlder) {
+      // Read the live DOM scroll position instead of the cached ref so we get
+      // the correct value even when scrollToBottom() has been called but the
+      // async scroll event hasn't updated the ref yet (common on initial mount).
+      const liveMeasures = scrollContainerMeasures();
+      const hasOverflow = liveMeasures.scrollHeight > liveMeasures.offsetHeight;
+      const liveScrollTop = liveMeasures.scrollTop;
+
       // Older-page pagination uses one of three modes:
       // - `stick-to-top`: user hit the absolute top and wants to keep reading upward
       // - `preserve-anchor`: user was only near the top, so keep the same message in view
       // - `idle`: no restoration needed for this load cycle
-      if (scrollTop.current <= 1) {
+      //
+      // When the container doesn't overflow yet (e.g. content hasn't reached its
+      // final height due to font loading) the scroll position is meaningless, so
+      // default to idle to avoid a false stick-to-top that would jump the list.
+      if (!hasOverflow) {
+        olderPaginationState.current = {
+          anchor: null,
+          mode: 'idle',
+        };
+      } else if (liveScrollTop <= 1) {
         olderPaginationState.current = {
           anchor: null,
           mode: 'stick-to-top',
         };
-      } else if (scrollTop.current < loadMoreScrollThreshold) {
+      } else if (liveScrollTop < loadMoreScrollThreshold) {
         const capturedAnchor = captureAnchor();
         if (capturedAnchor) {
           olderPaginationState.current = {
diff --git a/src/components/MessageList/hooks/MessageList/useScrollLocationLogic.tsx b/src/components/MessageList/hooks/MessageList/useScrollLocationLogic.tsx
@@ -393,6 +393,7 @@ export const useScrollLocationLogic = (params: UseScrollLocationLogicParams) =>
     scrollContainerMeasures: () => ({
       offsetHeight: listElement?.offsetHeight || 0,
       scrollHeight: listElement?.scrollHeight || 0,
+      scrollTop: listElement?.scrollTop || 0,
     }),
     scrolledUpThreshold,
     scrollToBottom,
diff --git a/src/components/MessageList/hooks/__tests__/useMessageListScrollManager.test.tsx b/src/components/MessageList/hooks/__tests__/useMessageListScrollManager.test.tsx
@@ -24,6 +24,7 @@ const defaultInputs: any = {
   scrollContainerMeasures: () => ({
     offsetHeight: 200,
     scrollHeight: 2000,
+    scrollTop: 0,
   }),
   scrolledUpThreshold: 200,
   scrollToBottom: () => {},
