FlashList v2 Chat UX Regression: Inconsistent scroll behavior with paginated messages

[EL-BADI]

Summary

After migrating from FlashList v1 to v2, chat interfaces with paginated message loading experience a confusing UX regression where the scroll direction for viewing messages and loading more messages are inconsistent.

Expected Behavior (v1 with inverted={true})

• ✅ Latest messages appear at the bottom
• ✅ Users scroll up to see older messages
• ✅ Users scroll up to trigger onEndReached and load more messages
• ✅ Consistent scroll direction for both viewing and loading

Current Behavior (v2 with maintainVisibleContentPosition)

• ❌ Latest messages appear at the top
• ❌ Users scroll down to see older messages
• ❌ Users must scroll up to trigger onStartReached and load more messages
• ❌ Inconsistent scroll direction: down to view, up to load more

Context

This issue occurs in a chat application where messages are loaded via paginated Convex queries. The typical flow is:

1. Initial load: Fetch most recent N messages
2. User scrolls to view older messages
3. Trigger pagination to load next batch of older messages
4. New messages arrive in real-time and are appended

Problem Description

In v2, the deprecation of inverted prop forces developers to use maintainVisibleContentPosition with startRenderingFromBottom: true. However, this creates a fundamental UX issue:

1. Visual Layout: Messages appear with newest at top (like Twitter/social feeds)
2. Loading Pattern: Must scroll to opposite direction to load more content
3. User Confusion: Users expect to scroll in one direction for both viewing and loading

Code Examples

v1 Implementation (Working UX with Convex pagination)

<FlashList
  data={messages} // From usePaginatedQuery(api.messages.list)
  renderItem={renderMessage}
  inverted={true}
  onEndReached={() => {
    // Load more older messages via Convex pagination
    loadMore();
  }}
  onEndReachedThreshold={0.5}
/>

v2 Implementation (Broken UX with Convex pagination)

<FlashList
  data={messages} // From usePaginatedQuery(api.messages.list)
  renderItem={renderMessage}
  maintainVisibleContentPosition={{
    startRenderingFromBottom: true,
    autoscrollToBottomThreshold: 0.2,
  }}
  onStartReached={() => {
    // Load more older messages - but user scrolled DOWN to see old messages!
    loadMore(); // This creates cognitive dissonance
  }}
  onStartReachedThreshold={0.5}
/>

Workaround Attempts

1. Using onEndReached instead of onStartReached

<FlashList
  data={messages}
  maintainVisibleContentPosition={{
    startRenderingFromBottom: true,
  }}
  onEndReached={loadMoreMessages} // This doesn't work as expected
  onEndReachedThreshold={0.5}
/>

Result: onEndReached doesn't trigger when scrolling up from the bottom.

2. Reversing data and using regular top-to-bottom layout

const reversedMessages = [...messages].reverse();

<FlashList
  data={reversedMessages}
  maintainVisibleContentPosition={{
    autoscrollToTopThreshold: 0.2,
  }}
  onEndReached={loadMoreMessages}
  onEndReachedThreshold={0.5}
/>

Result: Loses the natural chat feel where new messages appear at the bottom.

Proposed Solutions

Option 1: Bring back inverted prop

The simplest solution would be to un-deprecate the inverted prop and maintain it alongside maintainVisibleContentPosition.

Option 2: Smart callback detection

FlashList could automatically detect when maintainVisibleContentPosition.startRenderingFromBottom is true and swap the behavior of onStartReached and onEndReached to maintain consistent UX.

Option 3: New chat-specific props

Add dedicated chat interface props:

<FlashList
  chatMode={true} // Enables chat-optimized behavior
  onLoadMoreMessages={loadMoreMessages}
/>

Impact

This affects every chat application using paginated queries (like Convex, Firebase, or custom pagination APIs) when migrating from v1 to v2. The current v2 implementation forces developers to choose between:

• Maintaining familiar chat UX (latest messages at bottom) with confusing load-more behavior
• Having consistent scroll directions but unfamiliar message layout

The pagination aspect makes this particularly problematic because users expect a natural flow: scroll to see older content → load more older content in the same scroll direction.

Environment

• FlashList: ^2.0.3
• React Native: [your RN version]
• Platform: Android

Additional Context

Chat interfaces are one of the most common use cases for FlashList, and this regression significantly impacts user experience. The v1 inverted approach was intuitive and worked perfectly for chat applications.

---

Is there a recommended pattern for maintaining v1-style chat UX in v2, or would the team consider addressing this as a feature gap?

[naqvitalha]

Hey @EL-BADI, thanks for reporting this. I've update the docs now. You just needed to reverse your message and then it'll behave in the same way.

[EL-BADI]

Chat scroll jumps when loading more messages in FlashList v2

Issue: After migrating from FlashList v1 to v2, pagination causes weird scroll jumps when loading older messages.

Root Cause: The issue is caused by manually reversing the messages array combined with maintainVisibleContentPosition. FlashList v2's scroll position calculations get confused when the data order is manipulated while it's trying to maintain scroll position during pagination.

// This causes scroll jumps in v2:
const reversedMessages = React.useMemo(() => {
  if (!messages || messages.length === 0) return [];
  return messages.slice().reverse(); // ❌ Problematic with v2
}, [messages]);

<FlashList
  data={reversedMessages}
  maintainVisibleContentPosition={{
    autoscrollToBottomThreshold: 0.2,
    startRenderingFromBottom: true,
  }}
  onStartReached={debouncedHandleLoadMore}
/>

Even though the docs mention reversing messages for chat interfaces, this approach conflicts with v2's improved maintainVisibleContentPosition implementation and causes the scroll jumps during infinite loading.

Thanks to the Shopify team for the amazing work on FlashList v2! 🚀

[JClackett]

Yep, "happy" other people are experiencing the same as me as I was losing my mind trying to figure out what I was doing wrong.

When using convex and infinite pagination, and trying to render messages in reverse - the list doesnt "maintainVisibleContentPosition" it just stays at the top of the scroll view and the older messages are just in view.

I would love it if there was an example repo from shopify which displays this type of functionality, because there's so many different things to consider and its so easy to miss what is needed (plus I also think it's just straight up not working as intended :D )

ScreenRecording_08-25-2025.14-37-53_1.MP4

         <FlashList
            ref={flatListRef}
            extraData={messages.length > 0}
            onScroll={handleScroll}
            onStartReached={() => {
              if (status === "CanLoadMore") {
                void loadMore(DEFAULT_PAGINATION_NUM_ITEMS)
              }
            }}
            onStartReachedThreshold={0.2}
            showsVerticalScrollIndicator={false}
            data={messages}
            maintainVisibleContentPosition={{
              startRenderingFromBottom: true,
              animateAutoScrollToBottom: true,
              autoscrollToBottomThreshold: 0.1,
              autoscrollToTopThreshold: 0.1,
            }}

[naqvitalha]

Our fixture has a sample. @JClackett The reason it isn't working for you is because you don't have a keyExtractor. I'd include a warning in code for this.

[JClackett]

@naqvitalha I accidentally missed that, I actually do have one:

keyExtractor={(item, index) => {
   if (typeof item === "string") return `${item}-${index}`
   return item._id
}}

still does the same thing

[JClackett]

@naqvitalha looking at the fixture its quite a basic example that doesn't have any form of pagination, have you tested using the onStartReached callback and "prepending" items to the list?

[EL-BADI]

[@naqvitalha](https://github.com/naqvitalha) looking at the fixture its quite a basic example that doesn't have any form of pagination, have you tested using the onStartReached callback and "prepending" items to the list?

I have the same setup as you - I'm using Convex for paginated messages. As a temporary solution, I switched to the Legend List implementation and it's working perfectly until FlashList fixes this issue.

Working Solution with Legend List

Here's my implementation that handles pagination correctly:

// MessageList.tsx - Updated with worklet animations and reply preview height
import { LegendListRef } from "@legendapp/list";
import { AnimatedLegendList } from "@legendapp/list/reanimated";
import * as React from "react";
import Animated, {
  FadeIn,
  FadeOut,
  SharedValue,
  useAnimatedStyle,
  withSpring,
} from "react-native-reanimated";
import { Id } from "~/convex/_generated/dataModel";
import { MessagesListSkeleton } from "./chat-skeletons";
import { MessageItem } from "./message-item/message-item";
import { ChatConversation, ChatMessage } from "./types";

interface MessageListProps {
  messages: ChatMessage[] | undefined;
  userId: Id<"users">;
  conversation: ChatConversation | undefined;
  handleLoadMore: () => void;
  status: string;
  onReply?: (message: ChatMessage) => void;
  // New prop for keyboard synchronization
  keyboardHeight: SharedValue<number>;
  isReplyPreviewVisible: boolean;
}

export const MessageList = React.memo(
  ({
    messages,
    userId,
    conversation,
    handleLoadMore,
    status,
    onReply,
    keyboardHeight,
    isReplyPreviewVisible,
  }: MessageListProps) => {
    const [isLoadingMore, setIsLoadingMore] = React.useState(false);
    const [init, setInit] = React.useState(true);
    const [hasLayout, setHasLayout] = React.useState(false);

    const reversedMessages = React.useMemo(() => {
      if (!messages || messages.length === 0) return [];

      // Use slice() to create shallow copy, then reverse
      // This is more performant than [...messages].reverse() for large arrays
      return messages.slice().reverse();
    }, [messages]);

    const convId = conversation?._id;
    const listRef = React.useRef<LegendListRef>(null);
    
    // Reset gating whenever the conversation changes
    React.useEffect(() => {
      setInit(true);
      setHasLayout(false);
      setIsLoadingMore(false);
    }, [convId]);

    // Perform initial scroll after layout and data are ready, then unhide
    React.useEffect(() => {
      if (!init) return;
      if (!hasLayout) return;
      if (reversedMessages.length === 0) return;

      // Ensure we are anchored at the end before first visible frame
      listRef.current?.scrollToEnd({ animated: false });

      requestAnimationFrame(() => {
        setInit(false);
      });
    }, [init, hasLayout, reversedMessages]);

    // Worklet animation for messages list with reply preview height
    const animatedListStyle = useAnimatedStyle(() => {
      "worklet";

      // Calculate total offset including reply preview
      const replyPreviewOffset = isReplyPreviewVisible ? 110 : 0;
      const totalOffset = keyboardHeight.value + replyPreviewOffset;

      // Create a smooth upward movement that's synchronized with input and reply preview
      const translateY = withSpring(-totalOffset * 0.95, {
        damping: 50,
        stiffness: 400,
        mass: 0.6,
        restSpeedThreshold: 0.1,
        restDisplacementThreshold: 0.1,
      });

      return {
        transform: [{ translateY }],
      };
    }, [keyboardHeight, isReplyPreviewVisible]);

    // Debounced load more function
    const debouncedHandleLoadMore = React.useCallback(() => {
      if (isLoadingMore || status !== "CanLoadMore" || init) return;

      setIsLoadingMore(true);
      handleLoadMore();

      setTimeout(() => {
        setIsLoadingMore(false);
      }, 500);
    }, [handleLoadMore, status, isLoadingMore, init]);

    const keyExtractor = React.useCallback((item: ChatMessage) => {
      return item?._id ?? "unknown";
    }, []);

    const renderItem = React.useCallback(
      ({ item }: { item: ChatMessage }) => (
        <MessageItem
          item={item}
          userId={userId}
          conversation={conversation}
          onReply={onReply}
        />
      ),
      [userId, conversation, onReply]
    );

    if (messages === undefined || messages.length === 0) {
      return (
        <Animated.View
          entering={FadeIn.duration(300)}
          exiting={FadeOut.duration(200)}
          style={[{ flex: 1 }, animatedListStyle]}
        >
          <MessagesListSkeleton />
        </Animated.View>
      );
    }

    return (
      <Animated.View
        style={[{ flex: 1, position: "relative" }, animatedListStyle]}
        onLayout={() => {
          if (!hasLayout) {
            setHasLayout(true);
          }
        }}
      >
        <AnimatedLegendList
          ref={listRef}
          data={reversedMessages}
          recycleItems
          renderItem={renderItem}
          keyExtractor={keyExtractor}
          contentContainerStyle={{
            padding: 10,
          }}
          // chat interface props
          alignItemsAtEnd
          maintainScrollAtEnd
          maintainVisibleContentPosition
          maintainScrollAtEndThreshold={0.5}
          // waitForInitialLayout={true}
          // getFixedItemSize={(i, item) => {
          //   if (item.photoUrl) return 230;
          //   if (item.replyTo) return 150;
          //   return 80;
          // }}
          onStartReached={debouncedHandleLoadMore}
          onStartReachedThreshold={0.7}
          // ListHeaderComponent={HeaderComponent}
          getItemType={(item) => {
            if (item.photoUrl) return "photo";
            if (item.replyTo) return "reply";
            return "text";
          }}
          decelerationRate={0.975}
          showsVerticalScrollIndicator={false}
          // Keep list mounted for measurement but invisible until init is false
          style={[{ flex: 1, opacity: init ? 0 : 1 }]}
          pointerEvents={init ? "none" : "auto"}
        />

        {init ? (
          <Animated.View
            style={{
              position: "absolute",
              top: 0,
              bottom: 0,
              left: 0,
              right: 0,
            }}
          >
            <MessagesListSkeleton />
          </Animated.View>
        ) : null}
      </Animated.View>
    );
  }
);

MessageList.displayName = "MessageList";

Key Features That Work:

• ✅ Proper pagination with onStartReached callback
• ✅ Message prepending without scroll jumps
• ✅ Performance optimizations with recycleItems and proper memoization

Hope this helps others facing the same issue!

[naqvitalha]

@JClackett The sample already has onStartReached setup. If you scroll up in the fixture, it will pre-pend data. You can play with the sample directly here: https://snack.expo.dev/@naqvitalha/chat-sample
If you can provide a similar repro on expo snack, I can debug more easily. I'd also suggest removing the index from the keyExtractor and trying again.

[JClackett]

@naqvitalha fyi, removing index from key extractor didn't change anything

@EL-BADI its close with legend list but still pretty inconsistent, sometimes it maintains scroll, sometimes not - sometimes doesnt start at the bottom, plus a load of other random glitches, so frustrating :(

@naqvitalha will try get a repro which matches my setup - it has to be some intersection between infinite pagination, reversed messages, multiple item types (headers + messages), also keyboard aware views.

[lucasFigueira1]

@EL-BADI @naqvitalha
I was having the exact same problem as you, a really weird scroll behavior when navigating to a chat screen.
Sometimes the scroll wouldn't even return to the bottom, it would stop at a random point, as you can see in the video:

Grabacion.de.pantalla.2025-08-26.a.la.s.8.24.55.p.m.mov

The problem turned out to be the keyExtractor function, specifically this condition: return item?._id ?? "unknown";, I removed it and the issue got fixed.

Maybe a way for you to avoid doing this condition is to format previously the messages, if any message doesn't have id prop, you mock it there instead of handling it inside the key extractor.

I don't know why this fixes it, but it does...

[lucasFigueira1]

@naqvitalha I've noticed that also when using ListHeaderComponent and/or ListFooterComponent with a useMemo or useCallback that has dependencies, FlashList shows the same weird scroll behavior. When the header/footer are stable (no deps), it works fine. Any idea why this causes this issue too?

[mstfmedeni]

@EL-BADI @JClackett Have you found a logical solution for a fluid messaging interface?

[EL-BADI]

I reverted to v1, and everything is working seamlessly with the inverted prop.